{ "openapi": "3.1.0", "info": { "title": "Crush The Market Agent API", "version": "1.0.0", "summary": "Stock screening, company analysis and SEC filing tools over Crush The Market data.", "description": "Structured stock data for agents: search and score companies, screen the universe on 106 criteria, back-test a screen, and read the filings behind a score.\n\nEvery call needs an API key sent as `Authorization: Bearer ctm_live_...`. Create an account and a key at https://crushthemarket.com/subscribe\n\nThe free tier allows 12 agent calls per window; Pro is unmetered. Every response carries a `quota` block and `X-Quota-*` headers.\n\nThe same tools are available over MCP at `/api/mcp` (JSON-RPC 2.0, Streamable HTTP in JSON response mode).\n\nData, not advice. Do your own diligence." }, "servers": [ { "url": "https://crushthemarket.com", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "free", "description": "Available on the free tier, within the call allowance." }, { "name": "pro", "description": "Needs a Pro subscription: https://crushthemarket.com/subscribe" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "ctm_live_...", "description": "An API key from your Crush The Market account page. Get one at https://crushthemarket.com/subscribe. The key may also be sent as a bare `Authorization` value, or as `?key=` in the query string -- the header is preferred, because a query string is visible in access logs." } }, "schemas": { "Error": { "type": "object", "description": "The only error shape this API emits. Never a bare string, never HTML.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable snake_case code. Branch on this, never on the message.", "enum": [ "bad_request", "unknown_criterion", "missing_key", "invalid_key", "requires_pro", "email_unverified", "unknown_symbol", "not_covered", "no_analysis", "quota_exhausted", "rate_limited", "internal" ] }, "message": { "type": "string", "description": "A human sentence, safe to relay to an end user verbatim. Where an action is available the URL is inline." } } }, "quota": { "type": "object", "description": "The caller's agent-call allowance. `limit` is null on Pro, which is unmetered.", "properties": { "used": { "type": "integer" }, "limit": { "type": [ "integer", "null" ] }, "reset_at": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "Quota": { "type": "object", "description": "The caller's agent-call allowance. `limit` is null on Pro, which is unmetered.", "properties": { "used": { "type": "integer" }, "limit": { "type": [ "integer", "null" ] }, "reset_at": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "paths": { "/api/v1/search_companies": { "post": { "operationId": "search_companies", "summary": "Find covered companies by name or ticker.", "description": "Resolves a company name or ticker to the symbols Crush The Market covers. Search reads the profile table, so a company appears here even if it has not been scored yet -- call get_company to find out. ETFs are never returned: nothing feeds us fund holdings, so they cannot be scored.\n\nRequires a Crush The Market API key; calls without one fail. Create an account and a key at https://crushthemarket.com/subscribe\n\nArguments may also be sent as a query string with `GET` on the same path. `POST` is documented because nested arguments (a screen's `criteria`, for instance) cannot be expressed in a query string.\n\nExamples:\n- `{\"query\":\"Apple\"}` -- Name search; the exact ticker sorts first when one matches.\n- `{\"query\":\"AZN.L\",\"limit\":5}` -- London listings carry the `.L` suffix.\n\nTool-specific failures:\n- `bad_request` -- `query` is empty, or is only punctuation that gets stripped.\n\nRelated: `get_company`, `screen_stocks`.", "tags": [ "free" ], "requestBody": { "description": "The tool's arguments. An argument the tool does not declare is rejected, not ignored.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "A company name or ticker. Matched as a prefix against both.", "examples": [ "Apple" ] }, "limit": { "type": "number", "description": "How many results to return, 1-25. Defaults to 10.", "examples": [ 10 ] } }, "additionalProperties": false, "required": [ "query" ] }, "examples": { "example1": { "summary": "Name search; the exact ticker sorts first when one matches.", "value": { "query": "Apple" } }, "example2": { "summary": "London listings carry the `.L` suffix.", "value": { "query": "AZN.L", "limit": 5 } } } } } }, "responses": { "200": { "description": "The tool ran. A response carrying an `error` block never reaches this status -- a domain miss is mapped to its own status, so a 200 means a hit.", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Only these fields are emitted. Declared in the registry as `query`, `count`, `results`, `error`, `as_of`, `source`, `disclaimer`, plus the provenance and quota block every response carries.", "properties": { "query": {}, "count": {}, "results": {}, "error": { "description": "Present when the lookup missed. The call itself succeeded; see the status code." }, "as_of": {}, "source": {}, "disclaimer": {}, "quota": { "type": "object", "description": "The caller's agent-call allowance. `limit` is null on Pro, which is unmetered.", "properties": { "used": { "type": "integer" }, "limit": { "type": [ "integer", "null" ] }, "reset_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "notice": { "description": "Present only when the allowance is nearly spent." } } } } } }, "400": { "description": "`bad_request` -- the tool name is unknown, or an argument is missing, mistyped, or not one the tool declares (an undeclared argument is rejected, never ignored); `unknown_criterion` -- a criterion id is not one this API screens on", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "bad_request", "unknown_criterion" ] } } } } } ] } } } }, "401": { "description": "`missing_key` -- no API key was presented; `invalid_key` -- the key is unknown, malformed, or has been revoked", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "missing_key", "invalid_key" ] } } } } } ] } } } }, "402": { "description": "`requires_pro` -- the tool needs a Crush The Market Pro subscription and the caller is on the free tier", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "requires_pro" ] } } } } } ] } } } }, "403": { "description": "`email_unverified` -- the account that owns the key has not verified its email address", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "email_unverified" ] } } } } } ] } } } }, "404": { "description": "`unknown_symbol` -- no such ticker; `not_covered` -- the symbol exists but is outside coverage; `no_analysis` -- the symbol is covered but has not been scored yet", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unknown_symbol", "not_covered", "no_analysis" ] } } } } } ] } } } }, "429": { "description": "`quota_exhausted` -- the free allowance is spent; upgrade or wait for the reset named in the message; `rate_limited` -- too many calls too quickly; wait the number of seconds in Retry-After", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "quota_exhausted", "rate_limited" ] } } } } } ] } } } }, "500": { "description": "`internal` -- the server failed to handle the request", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal" ] } } } } } ] } } } } } } }, "/api/v1/get_company": { "post": { "operationId": "get_company", "summary": "Profile, the six scores, and the plain-English readings for one symbol.", "description": "Returns the stored profile, the six composite scores (value, growth, financial health, dividend, management, total, each 0-100), the ranked strengths and risks, the one-line verdict per section, and a coverage block naming where the data came from and whether the filing tools will return anything for this symbol. A score of null means too few of its legs could be computed -- it is NOT a bad score.\n\nRequires a Crush The Market API key; calls without one fail. Create an account and a key at https://crushthemarket.com/subscribe\n\nArguments may also be sent as a query string with `GET` on the same path. `POST` is documented because nested arguments (a screen's `criteria`, for instance) cannot be expressed in a query string.\n\nExamples:\n- `{\"symbol\":\"AAPL\"}` -- A US filer: EDGAR statements and filings both available.\n- `{\"symbol\":\"AZN.L\"}` -- A London listing with an SEC-registered ADR, so filings are 20-F.\n\nTool-specific failures:\n- `bad_request` -- `symbol` is missing or empty.\n- `unknown_symbol` -- No profile is held for the symbol at all.\n- `not_covered` -- The symbol is an ETF. No feed supplies fund holdings, so ETFs are never scored.\n- `no_analysis` -- The company is covered but has no scored row yet.\n\nRelated: `search_companies`, `explain_metric`, `screen_stocks`.", "tags": [ "free" ], "requestBody": { "description": "The tool's arguments. An argument the tool does not declare is rejected, not ignored.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "The ticker as Crush The Market spells it. London listings carry a `.L` suffix.", "examples": [ "AAPL" ] } }, "additionalProperties": false, "required": [ "symbol" ] }, "examples": { "example1": { "summary": "A US filer: EDGAR statements and filings both available.", "value": { "symbol": "AAPL" } }, "example2": { "summary": "A London listing with an SEC-registered ADR, so filings are 20-F.", "value": { "symbol": "AZN.L" } } } } } }, "responses": { "200": { "description": "The tool ran. A response carrying an `error` block never reaches this status -- a domain miss is mapped to its own status, so a 200 means a hit.", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Only these fields are emitted. Declared in the registry as `symbol`, `profile`, `scores`, `readings`, `coverage`, `error`, `as_of`, `source`, `disclaimer`, plus the provenance and quota block every response carries.", "properties": { "symbol": {}, "profile": {}, "scores": {}, "readings": {}, "coverage": {}, "error": { "description": "Present when the lookup missed. The call itself succeeded; see the status code." }, "as_of": {}, "source": {}, "disclaimer": {}, "quota": { "type": "object", "description": "The caller's agent-call allowance. `limit` is null on Pro, which is unmetered.", "properties": { "used": { "type": "integer" }, "limit": { "type": [ "integer", "null" ] }, "reset_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "notice": { "description": "Present only when the allowance is nearly spent." } } } } } }, "400": { "description": "`bad_request` -- the tool name is unknown, or an argument is missing, mistyped, or not one the tool declares (an undeclared argument is rejected, never ignored); `unknown_criterion` -- a criterion id is not one this API screens on", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "bad_request", "unknown_criterion" ] } } } } } ] } } } }, "401": { "description": "`missing_key` -- no API key was presented; `invalid_key` -- the key is unknown, malformed, or has been revoked", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "missing_key", "invalid_key" ] } } } } } ] } } } }, "402": { "description": "`requires_pro` -- the tool needs a Crush The Market Pro subscription and the caller is on the free tier", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "requires_pro" ] } } } } } ] } } } }, "403": { "description": "`email_unverified` -- the account that owns the key has not verified its email address", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "email_unverified" ] } } } } } ] } } } }, "404": { "description": "`unknown_symbol` -- no such ticker; `not_covered` -- the symbol exists but is outside coverage; `no_analysis` -- the symbol is covered but has not been scored yet", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unknown_symbol", "not_covered", "no_analysis" ] } } } } } ] } } } }, "429": { "description": "`quota_exhausted` -- the free allowance is spent; upgrade or wait for the reset named in the message; `rate_limited` -- too many calls too quickly; wait the number of seconds in Retry-After", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "quota_exhausted", "rate_limited" ] } } } } } ] } } } }, "500": { "description": "`internal` -- the server failed to handle the request", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal" ] } } } } } ] } } } } } } }, "/api/v1/explain_metric": { "post": { "operationId": "explain_metric", "summary": "What one screening criterion means, and how to filter on it.", "description": "Explains a criterion id: its human label, the operators it accepts, the JSON type its value must have, and the written definition from the matching documentation page. Use it before screen_stocks when you are unsure what a criterion measures or how to phrase a filter. Not every criterion has a documentation page; `definition` and `explanation` are null when it does not.\n\nRequires a Crush The Market API key; calls without one fail. Create an account and a key at https://crushthemarket.com/subscribe\n\nArguments may also be sent as a query string with `GET` on the same path. `POST` is documented because nested arguments (a screen's `criteria`, for instance) cannot be expressed in a query string.\n\nExamples:\n- `{\"criterion_id\":\"priceToEarningsRatio\"}` -- A numeric criterion with More Than / Less Than.\n- `{\"criterion_id\":\"dividend\"}` -- A boolean criterion: operators are True and False, and it takes no value.\n\nTool-specific failures:\n- `bad_request` -- `criterion_id` is missing or empty.\n- `unknown_criterion` -- The id is not one of the published screening criteria.\n\nRelated: `screen_stocks`, `get_company`.", "tags": [ "free" ], "requestBody": { "description": "The tool's arguments. An argument the tool does not declare is rejected, not ignored.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "criterion_id": { "type": "string", "description": "A screening criterion id, exactly as screen_stocks accepts it.", "examples": [ "priceToEarningsRatio" ] } }, "additionalProperties": false, "required": [ "criterion_id" ] }, "examples": { "example1": { "summary": "A numeric criterion with More Than / Less Than.", "value": { "criterion_id": "priceToEarningsRatio" } }, "example2": { "summary": "A boolean criterion: operators are True and False, and it takes no value.", "value": { "criterion_id": "dividend" } } } } } }, "responses": { "200": { "description": "The tool ran. A response carrying an `error` block never reaches this status -- a domain miss is mapped to its own status, so a 200 means a hit.", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Only these fields are emitted. Declared in the registry as `criterion`, `definition`, `explanation`, `doc_url`, `error`, `as_of`, `source`, `disclaimer`, plus the provenance and quota block every response carries.", "properties": { "criterion": {}, "definition": {}, "explanation": {}, "doc_url": {}, "error": { "description": "Present when the lookup missed. The call itself succeeded; see the status code." }, "as_of": {}, "source": {}, "disclaimer": {}, "quota": { "type": "object", "description": "The caller's agent-call allowance. `limit` is null on Pro, which is unmetered.", "properties": { "used": { "type": "integer" }, "limit": { "type": [ "integer", "null" ] }, "reset_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "notice": { "description": "Present only when the allowance is nearly spent." } } } } } }, "400": { "description": "`bad_request` -- the tool name is unknown, or an argument is missing, mistyped, or not one the tool declares (an undeclared argument is rejected, never ignored); `unknown_criterion` -- a criterion id is not one this API screens on", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "bad_request", "unknown_criterion" ] } } } } } ] } } } }, "401": { "description": "`missing_key` -- no API key was presented; `invalid_key` -- the key is unknown, malformed, or has been revoked", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "missing_key", "invalid_key" ] } } } } } ] } } } }, "402": { "description": "`requires_pro` -- the tool needs a Crush The Market Pro subscription and the caller is on the free tier", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "requires_pro" ] } } } } } ] } } } }, "403": { "description": "`email_unverified` -- the account that owns the key has not verified its email address", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "email_unverified" ] } } } } } ] } } } }, "404": { "description": "`unknown_symbol` -- no such ticker; `not_covered` -- the symbol exists but is outside coverage; `no_analysis` -- the symbol is covered but has not been scored yet", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unknown_symbol", "not_covered", "no_analysis" ] } } } } } ] } } } }, "429": { "description": "`quota_exhausted` -- the free allowance is spent; upgrade or wait for the reset named in the message; `rate_limited` -- too many calls too quickly; wait the number of seconds in Retry-After", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "quota_exhausted", "rate_limited" ] } } } } } ] } } } }, "500": { "description": "`internal` -- the server failed to handle the request", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal" ] } } } } } ] } } } } } } }, "/api/v1/screen_stocks": { "post": { "operationId": "screen_stocks", "summary": "Filter the scored universe on one or more criteria.", "description": "Runs the same screen the website runs. `criteria` is a list of `{ id, operator, value }`, where a numeric operator is `>`, `<`, `>=` or `<=` (the word forms `More Than` / `Less Than` also work); call explain_metric for what an id means and which operators it accepts. Every response carries `universe_size` -- how many symbols in the selected markets had a scored row to filter at all. Read it before reporting an empty result: zero matches out of zero scored symbols is a coverage gap, not a finding about the market.\n\nRequires a Crush The Market API key; calls without one fail. Create an account and a key at https://crushthemarket.com/subscribe\n\nArguments may also be sent as a query string with `GET` on the same path. `POST` is documented because nested arguments (a screen's `criteria`, for instance) cannot be expressed in a query string.\n\nExamples:\n- `{\"criteria\":[{\"id\":\"priceToEarningsRatio\",\"operator\":\"<\",\"value\":15}],\"markets\":[\"sp500\"]}` -- A single numeric filter over the S&P 500. `<` and `>` are the operators; `Less Than` and `More Than` mean the same thing.\n- `{\"criteria\":[{\"id\":\"valueScore\",\"operator\":\">=\",\"value\":50}],\"markets\":[\"sp500\"]}` -- `>=` keeps the companies sitting exactly on 50, which `>` drops.\n- `{\"criteria\":[{\"id\":\"dividend\",\"operator\":\"True\"},{\"id\":\"financialScore\",\"operator\":\">\",\"value\":70}]}` -- A boolean criterion takes no `value`; the operator is the value.\n\nTool-specific failures:\n- `bad_request` -- `criteria` is empty or malformed, a criterion id is not published, an operator is not one the criterion accepts (`>=` needs a criterion that compares numerically, so a boolean or list criterion rejects it), or two criteria filter the same column.\n\nRelated: `explain_metric`, `get_company`, `backtest_screen`.", "tags": [ "free" ], "requestBody": { "description": "The tool's arguments. An argument the tool does not declare is rejected, not ignored.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "criteria": { "type": "array", "items": { "type": "object" }, "description": "Filters, each `{ \"id\": , \"operator\": , \"value\": }`. A numeric criterion takes `>`, `<`, `>=` or `<=`; the word forms `More Than` and `Less Than` are accepted too, and case and surrounding spaces do not matter. `>=` and `<=` include the boundary value, `>` and `<` exclude it -- ask for the one you mean rather than nudging the number. A list criterion takes `in` or `not in` and a list of strings; a boolean criterion takes `True` or `False` and no `value`. Call explain_metric for the operators a given id accepts.", "examples": [ [ { "id": "priceToEarningsRatio", "operator": "<", "value": 15 } ] ] }, "markets": { "type": "array", "items": { "type": "string" }, "description": "Which universes to screen. One or more of: sp500, ftse100, russell1000, ftseallshare, djia, nasdaq100. Defaults to sp500 and ftse100.", "examples": [ [ "sp500" ] ] }, "limit": { "type": "number", "description": "How many rows to return, 1-100, highest total score first. Defaults to 25. The full match count is always in `count`.", "examples": [ 25 ] } }, "additionalProperties": false, "required": [ "criteria" ] }, "examples": { "example1": { "summary": "A single numeric filter over the S&P 500. `<` and `>` are the operators; `Less Than` and `More Than` mean the same thing.", "value": { "criteria": [ { "id": "priceToEarningsRatio", "operator": "<", "value": 15 } ], "markets": [ "sp500" ] } }, "example2": { "summary": "`>=` keeps the companies sitting exactly on 50, which `>` drops.", "value": { "criteria": [ { "id": "valueScore", "operator": ">=", "value": 50 } ], "markets": [ "sp500" ] } }, "example3": { "summary": "A boolean criterion takes no `value`; the operator is the value.", "value": { "criteria": [ { "id": "dividend", "operator": "True" }, { "id": "financialScore", "operator": ">", "value": 70 } ] } } } } } }, "responses": { "200": { "description": "The tool ran. A response carrying an `error` block never reaches this status -- a domain miss is mapped to its own status, so a 200 means a hit.", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Only these fields are emitted. Declared in the registry as `count`, `universe_size`, `markets`, `results`, `note`, `query`, `url`, `url_note`, `error`, `as_of`, `source`, `disclaimer`, plus the provenance and quota block every response carries.", "properties": { "count": {}, "universe_size": {}, "markets": {}, "results": {}, "note": {}, "query": {}, "url": {}, "url_note": {}, "error": { "description": "Present when the lookup missed. The call itself succeeded; see the status code." }, "as_of": {}, "source": {}, "disclaimer": {}, "quota": { "type": "object", "description": "The caller's agent-call allowance. `limit` is null on Pro, which is unmetered.", "properties": { "used": { "type": "integer" }, "limit": { "type": [ "integer", "null" ] }, "reset_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "notice": { "description": "Present only when the allowance is nearly spent." } } } } } }, "400": { "description": "`bad_request` -- the tool name is unknown, or an argument is missing, mistyped, or not one the tool declares (an undeclared argument is rejected, never ignored); `unknown_criterion` -- a criterion id is not one this API screens on", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "bad_request", "unknown_criterion" ] } } } } } ] } } } }, "401": { "description": "`missing_key` -- no API key was presented; `invalid_key` -- the key is unknown, malformed, or has been revoked", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "missing_key", "invalid_key" ] } } } } } ] } } } }, "402": { "description": "`requires_pro` -- the tool needs a Crush The Market Pro subscription and the caller is on the free tier", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "requires_pro" ] } } } } } ] } } } }, "403": { "description": "`email_unverified` -- the account that owns the key has not verified its email address", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "email_unverified" ] } } } } } ] } } } }, "404": { "description": "`unknown_symbol` -- no such ticker; `not_covered` -- the symbol exists but is outside coverage; `no_analysis` -- the symbol is covered but has not been scored yet", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unknown_symbol", "not_covered", "no_analysis" ] } } } } } ] } } } }, "429": { "description": "`quota_exhausted` -- the free allowance is spent; upgrade or wait for the reset named in the message; `rate_limited` -- too many calls too quickly; wait the number of seconds in Retry-After", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "quota_exhausted", "rate_limited" ] } } } } } ] } } } }, "500": { "description": "`internal` -- the server failed to handle the request", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal" ] } } } } } ] } } } } } } }, "/api/v1/backtest_screen": { "post": { "operationId": "backtest_screen", "summary": "Run a screen back through every year we hold and compare it to the market. Pro only.", "description": "Rebuilds the screen once per year of stored history, holds the cohort for `min_hold_years`, and reports the compound annual growth rate of the equal-weighted strategy against the equal-weighted market over the same years. Criteria and markets take the same shape as screen_stocks. `cohort_sizes` is one entry per ENTRY year, and `years` carries one more entry than that -- the trailing year the last cohort is sold in -- so do not zip the two. The figures are a property of the rows we hold, not a forecast, and a small `matched_symbols` means the result describes a handful of names.\n\nRequires a Crush The Market Pro subscription and an API key: https://crushthemarket.com/subscribe\n\nArguments may also be sent as a query string with `GET` on the same path. `POST` is documented because nested arguments (a screen's `criteria`, for instance) cannot be expressed in a query string.\n\nExamples:\n- `{\"criteria\":[{\"id\":\"totalScore\",\"operator\":\">\",\"value\":70}],\"markets\":[\"sp500\"]}` -- Yearly rebalance of everything scoring above 70. `>`, `<`, `>=` and `<=` are the numeric operators; `More Than` and `Less Than` mean the same as `>` and `<`.\n- `{\"criteria\":[{\"id\":\"dividend\",\"operator\":\"True\"}],\"min_hold_years\":3}` -- Hold each name three years before it can be dropped.\n\nTool-specific failures:\n- `requires_pro` -- The caller is not on an active subscription.\n- `bad_request` -- `criteria` is empty or malformed, a criterion id is not published, or an operator is not one the criterion accepts (`>=` needs a criterion that compares numerically, so a boolean or list criterion rejects it).\n\nRelated: `screen_stocks`, `explain_metric`.", "tags": [ "pro" ], "requestBody": { "description": "The tool's arguments. An argument the tool does not declare is rejected, not ignored.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "criteria": { "type": "array", "items": { "type": "object" }, "description": "Filters, each `{ \"id\": , \"operator\": , \"value\": }`. A numeric criterion takes `>`, `<`, `>=` or `<=`; the word forms `More Than` and `Less Than` are accepted too, and case and surrounding spaces do not matter. `>=` and `<=` include the boundary value, `>` and `<` exclude it -- ask for the one you mean rather than nudging the number. A list criterion takes `in` or `not in` and a list of strings; a boolean criterion takes `True` or `False` and no `value`. Call explain_metric for the operators a given id accepts.", "examples": [ [ { "id": "totalScore", "operator": ">", "value": 70 } ] ] }, "markets": { "type": "array", "items": { "type": "string" }, "description": "Which universes to screen. One or more of: sp500, ftse100, russell1000, ftseallshare, djia, nasdaq100. Defaults to sp500 and ftse100.", "examples": [ [ "sp500" ] ] }, "min_hold_years": { "type": "number", "description": "Whole years to hold a name before it can be dropped, 1-10. 1 is a classic yearly rebalance. Defaults to 1.", "examples": [ 1 ] } }, "additionalProperties": false, "required": [ "criteria" ] }, "examples": { "example1": { "summary": "Yearly rebalance of everything scoring above 70. `>`, `<`, `>=` and `<=` are the numeric operators; `More Than` and `Less Than` mean the same as `>` and `<`.", "value": { "criteria": [ { "id": "totalScore", "operator": ">", "value": 70 } ], "markets": [ "sp500" ] } }, "example2": { "summary": "Hold each name three years before it can be dropped.", "value": { "criteria": [ { "id": "dividend", "operator": "True" } ], "min_hold_years": 3 } } } } } }, "responses": { "200": { "description": "The tool ran. A response carrying an `error` block never reaches this status -- a domain miss is mapped to its own status, so a 200 means a hit.", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Only these fields are emitted. Declared in the registry as `strategy_cagr`, `market_cagr`, `years`, `min_hold_years`, `cohort_sizes`, `matched_symbols`, `universe_size`, `markets`, `note`, `query`, `url`, `url_note`, `error`, `as_of`, `source`, `disclaimer`, plus the provenance and quota block every response carries.", "properties": { "strategy_cagr": {}, "market_cagr": {}, "years": {}, "min_hold_years": {}, "cohort_sizes": {}, "matched_symbols": {}, "universe_size": {}, "markets": {}, "note": {}, "query": {}, "url": {}, "url_note": {}, "error": { "description": "Present when the lookup missed. The call itself succeeded; see the status code." }, "as_of": {}, "source": {}, "disclaimer": {}, "quota": { "type": "object", "description": "The caller's agent-call allowance. `limit` is null on Pro, which is unmetered.", "properties": { "used": { "type": "integer" }, "limit": { "type": [ "integer", "null" ] }, "reset_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "notice": { "description": "Present only when the allowance is nearly spent." } } } } } }, "400": { "description": "`bad_request` -- the tool name is unknown, or an argument is missing, mistyped, or not one the tool declares (an undeclared argument is rejected, never ignored); `unknown_criterion` -- a criterion id is not one this API screens on", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "bad_request", "unknown_criterion" ] } } } } } ] } } } }, "401": { "description": "`missing_key` -- no API key was presented; `invalid_key` -- the key is unknown, malformed, or has been revoked", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "missing_key", "invalid_key" ] } } } } } ] } } } }, "402": { "description": "`requires_pro` -- the tool needs a Crush The Market Pro subscription and the caller is on the free tier", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "requires_pro" ] } } } } } ] } } } }, "403": { "description": "`email_unverified` -- the account that owns the key has not verified its email address", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "email_unverified" ] } } } } } ] } } } }, "404": { "description": "`unknown_symbol` -- no such ticker; `not_covered` -- the symbol exists but is outside coverage; `no_analysis` -- the symbol is covered but has not been scored yet", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unknown_symbol", "not_covered", "no_analysis" ] } } } } } ] } } } }, "429": { "description": "`quota_exhausted` -- the free allowance is spent; upgrade or wait for the reset named in the message; `rate_limited` -- too many calls too quickly; wait the number of seconds in Retry-After", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "quota_exhausted", "rate_limited" ] } } } } } ] } } } }, "500": { "description": "`internal` -- the server failed to handle the request", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal" ] } } } } } ] } } } } } } }, "/api/v1/help": { "post": { "operationId": "help", "summary": "How to use these tools well, and what this data can and cannot answer.", "description": "Long-form guidance, in topics. Call it with no argument for the essentials and the topic list, or with `topic` for one of them. Reach for it when you are unsure which tool answers a question, whether the data supports the question at all, or what an error means. It returns no company data and costs nothing but the call.\n\nRequires a Crush The Market API key; calls without one fail. Create an account and a key at https://crushthemarket.com/subscribe\n\nArguments may also be sent as a query string with `GET` on the same path. `POST` is documented because nested arguments (a screen's `criteria`, for instance) cannot be expressed in a query string.\n\nExamples:\n- `{\"topic\":\"filings\"}` -- How to read an annual report without drowning in it\n\nTool-specific failures:\n- `bad_request` -- the `topic` argument is not a string\n\nRelated: `explain_metric`, `get_company`.", "tags": [ "free" ], "requestBody": { "description": "The tool's arguments. An argument the tool does not declare is rejected, not ignored.", "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "topic": { "type": "string", "description": "One of: start, answerable, screening, filings, scores, limits, errors, reporting. Omit for the essentials plus the topic list.", "examples": [ "filings" ] } }, "additionalProperties": false }, "examples": { "example1": { "summary": "How to read an annual report without drowning in it", "value": { "topic": "filings" } } } } } }, "responses": { "200": { "description": "The tool ran. A response carrying an `error` block never reaches this status -- a domain miss is mapped to its own status, so a 200 means a hit.", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Only these fields are emitted. Declared in the registry as `topic`, `title`, `text`, `topics`, `as_of`, `source`, `disclaimer`, plus the provenance and quota block every response carries.", "properties": { "topic": {}, "title": {}, "text": {}, "topics": {}, "as_of": {}, "source": {}, "disclaimer": {}, "quota": { "type": "object", "description": "The caller's agent-call allowance. `limit` is null on Pro, which is unmetered.", "properties": { "used": { "type": "integer" }, "limit": { "type": [ "integer", "null" ] }, "reset_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "notice": { "description": "Present only when the allowance is nearly spent." } } } } } }, "400": { "description": "`bad_request` -- the tool name is unknown, or an argument is missing, mistyped, or not one the tool declares (an undeclared argument is rejected, never ignored); `unknown_criterion` -- a criterion id is not one this API screens on", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "bad_request", "unknown_criterion" ] } } } } } ] } } } }, "401": { "description": "`missing_key` -- no API key was presented; `invalid_key` -- the key is unknown, malformed, or has been revoked", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "missing_key", "invalid_key" ] } } } } } ] } } } }, "402": { "description": "`requires_pro` -- the tool needs a Crush The Market Pro subscription and the caller is on the free tier", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "requires_pro" ] } } } } } ] } } } }, "403": { "description": "`email_unverified` -- the account that owns the key has not verified its email address", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "email_unverified" ] } } } } } ] } } } }, "404": { "description": "`unknown_symbol` -- no such ticker; `not_covered` -- the symbol exists but is outside coverage; `no_analysis` -- the symbol is covered but has not been scored yet", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unknown_symbol", "not_covered", "no_analysis" ] } } } } } ] } } } }, "429": { "description": "`quota_exhausted` -- the free allowance is spent; upgrade or wait for the reset named in the message; `rate_limited` -- too many calls too quickly; wait the number of seconds in Retry-After", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "quota_exhausted", "rate_limited" ] } } } } } ] } } } }, "500": { "description": "`internal` -- the server failed to handle the request", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal" ] } } } } } ] } } } } } } }, "/api/v1/list_filings": { "post": { "operationId": "list_filings", "summary": "Which SEC filings exist for a company, with accession numbers.", "description": "Lists a company's filings from the SEC EDGAR submissions index, newest first, each with its accession number -- the id every other filing tool takes. `latest_annual` names the report the other tools default to. An empty list is NEVER bare: `reason` distinguishes \"no SEC filer is mapped to this symbol\" from \"EDGAR gave us something we could not read\", and `adr_symbol` names the US-listed ADR to retry against where one exists. Read `reason` before telling anyone a company files nothing.\n\nRequires a Crush The Market API key; calls without one fail. Create an account and a key at https://crushthemarket.com/subscribe\n\nArguments may also be sent as a query string with `GET` on the same path. `POST` is documented because nested arguments (a screen's `criteria`, for instance) cannot be expressed in a query string.\n\nExamples:\n- `{\"symbol\":\"AAPL\",\"form\":\"10-K\"}` -- Every 10-K Apple has filed, newest first.\n- `{\"symbol\":\"AZN.L\"}` -- A London listing: no SEC filer is mapped to it, so `reason` is no_sec_filer and `adr_symbol` names the ticker that does file.\n\nTool-specific failures:\n- `bad_request` -- `symbol` is missing or empty.\n\nRelated: `get_filing_outline`, `read_filing_section`, `score_evidence`.", "tags": [ "free" ], "requestBody": { "description": "The tool's arguments. An argument the tool does not declare is rejected, not ignored.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "The ticker as Crush The Market spells it. London listings carry a `.L` suffix.", "examples": [ "AAPL" ] }, "form": { "type": "string", "description": "Return only this form, matched exactly: 10-K, 10-Q, 8-K, 20-F, 40-F.", "examples": [ "10-K" ] }, "limit": { "type": "number", "description": "How many filings to return, 1-100, newest first. Defaults to 20. The full match count is always in `total`.", "examples": [ 20 ] } }, "additionalProperties": false, "required": [ "symbol" ] }, "examples": { "example1": { "summary": "Every 10-K Apple has filed, newest first.", "value": { "symbol": "AAPL", "form": "10-K" } }, "example2": { "summary": "A London listing: no SEC filer is mapped to it, so `reason` is no_sec_filer and `adr_symbol` names the ticker that does file.", "value": { "symbol": "AZN.L" } } } } } }, "responses": { "200": { "description": "The tool ran. A response carrying an `error` block never reaches this status -- a domain miss is mapped to its own status, so a 200 means a hit.", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Only these fields are emitted. Declared in the registry as `symbol`, `count`, `total`, `filings`, `reason`, `reason_note`, `adr_symbol`, `latest_annual`, `note`, `error`, `as_of`, `source`, `disclaimer`, plus the provenance and quota block every response carries.", "properties": { "symbol": {}, "count": {}, "total": {}, "filings": {}, "reason": {}, "reason_note": {}, "adr_symbol": {}, "latest_annual": {}, "note": {}, "error": { "description": "Present when the lookup missed. The call itself succeeded; see the status code." }, "as_of": {}, "source": {}, "disclaimer": {}, "quota": { "type": "object", "description": "The caller's agent-call allowance. `limit` is null on Pro, which is unmetered.", "properties": { "used": { "type": "integer" }, "limit": { "type": [ "integer", "null" ] }, "reset_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "notice": { "description": "Present only when the allowance is nearly spent." } } } } } }, "400": { "description": "`bad_request` -- the tool name is unknown, or an argument is missing, mistyped, or not one the tool declares (an undeclared argument is rejected, never ignored); `unknown_criterion` -- a criterion id is not one this API screens on", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "bad_request", "unknown_criterion" ] } } } } } ] } } } }, "401": { "description": "`missing_key` -- no API key was presented; `invalid_key` -- the key is unknown, malformed, or has been revoked", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "missing_key", "invalid_key" ] } } } } } ] } } } }, "402": { "description": "`requires_pro` -- the tool needs a Crush The Market Pro subscription and the caller is on the free tier", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "requires_pro" ] } } } } } ] } } } }, "403": { "description": "`email_unverified` -- the account that owns the key has not verified its email address", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "email_unverified" ] } } } } } ] } } } }, "404": { "description": "`unknown_symbol` -- no such ticker; `not_covered` -- the symbol exists but is outside coverage; `no_analysis` -- the symbol is covered but has not been scored yet", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unknown_symbol", "not_covered", "no_analysis" ] } } } } } ] } } } }, "429": { "description": "`quota_exhausted` -- the free allowance is spent; upgrade or wait for the reset named in the message; `rate_limited` -- too many calls too quickly; wait the number of seconds in Retry-After", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "quota_exhausted", "rate_limited" ] } } } } } ] } } } }, "500": { "description": "`internal` -- the server failed to handle the request", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal" ] } } } } } ] } } } } } } }, "/api/v1/get_filing_outline": { "post": { "operationId": "get_filing_outline", "summary": "Every readable part of one filing, both lanes, with sizes.", "description": "The scan tool: call it before reading anything. Returns every addressable section of one filing -- by default the latest annual report -- across two lanes, each entry with a `section_id` for read_filing_section and a measured size so you can choose what to spend. The notes lane comes from EDGAR's own per-note rendering; read `notes.label` for what that category contains, because it is wider than the accounting notes alone. The narrative lane is regex-sectioned from the primary document and is SECOND CLASS: it carries `confidence`, `failure_reason` and `notice` at document level and `confidence`, `flags` and `notice` per section. Some filers incorporate MD&A by reference and print only a pointer where the disclosure should be; that section is flagged `incorporated_by_reference` and must not be read as the disclosure itself.\n\nRequires a Crush The Market API key; calls without one fail. Create an account and a key at https://crushthemarket.com/subscribe\n\nArguments may also be sent as a query string with `GET` on the same path. `POST` is documented because nested arguments (a screen's `criteria`, for instance) cannot be expressed in a query string.\n\nExamples:\n- `{\"symbol\":\"AAPL\"}` -- Both lanes of Apple's latest 10-K, every note sized.\n- `{\"symbol\":\"JPM\"}` -- A filer that incorporates MD&A by reference: `narrative.confidence` is degraded and Item 7 is flagged.\n\nTool-specific failures:\n- `bad_request` -- `symbol` is missing, or `accession` is not in the form 0000000000-00-000000.\n- `no_sec_filer` -- No SEC filer is mapped to the symbol. `adr_symbol` from list_filings may name one that is.\n- `no_annual_report_yet` -- EDGAR lists filings for the issuer but no annual report among them.\n- `unknown_filing` -- The accession is not one EDGAR lists for this symbol.\n- `filing_summary_missing` -- EDGAR has no FilingSummary.xml for the filing, so the notes lane cannot be built.\n- `edgar_unavailable` -- EDGAR did not answer, or answered with an error, after retries.\n\nRelated: `list_filings`, `read_filing_section`, `search_filing`, `score_evidence`.", "tags": [ "free" ], "requestBody": { "description": "The tool's arguments. An argument the tool does not declare is rejected, not ignored.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "The ticker as Crush The Market spells it.", "examples": [ "AAPL" ] }, "accession": { "type": "string", "description": "A specific filing, as list_filings spells it. Defaults to the latest annual report (10-K, 20-F or 40-F).", "examples": [ "0000320193-25-000079" ] }, "sizes": { "type": "boolean", "description": "Measure every note by fetching it, so `chars` and `tokens` are real rather than null. Defaults to true. Pass false for a cheaper outline when you do not need to budget.", "examples": [ true ] } }, "additionalProperties": false, "required": [ "symbol" ] }, "examples": { "example1": { "summary": "Both lanes of Apple's latest 10-K, every note sized.", "value": { "symbol": "AAPL" } }, "example2": { "summary": "A filer that incorporates MD&A by reference: `narrative.confidence` is degraded and Item 7 is flagged.", "value": { "symbol": "JPM" } } } } } }, "responses": { "200": { "description": "The tool ran. A response carrying an `error` block never reaches this status -- a domain miss is mapped to its own status, so a 200 means a hit.", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Only these fields are emitted. Declared in the registry as `symbol`, `filing`, `notes`, `narrative`, `note`, `error`, `as_of`, `source`, `disclaimer`, plus the provenance and quota block every response carries.", "properties": { "symbol": {}, "filing": {}, "notes": {}, "narrative": {}, "note": {}, "error": { "description": "Present when the lookup missed. The call itself succeeded; see the status code." }, "as_of": {}, "source": {}, "disclaimer": {}, "quota": { "type": "object", "description": "The caller's agent-call allowance. `limit` is null on Pro, which is unmetered.", "properties": { "used": { "type": "integer" }, "limit": { "type": [ "integer", "null" ] }, "reset_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "notice": { "description": "Present only when the allowance is nearly spent." } } } } } }, "400": { "description": "`bad_request` -- the tool name is unknown, or an argument is missing, mistyped, or not one the tool declares (an undeclared argument is rejected, never ignored); `unknown_criterion` -- a criterion id is not one this API screens on", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "bad_request", "unknown_criterion" ] } } } } } ] } } } }, "401": { "description": "`missing_key` -- no API key was presented; `invalid_key` -- the key is unknown, malformed, or has been revoked", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "missing_key", "invalid_key" ] } } } } } ] } } } }, "402": { "description": "`requires_pro` -- the tool needs a Crush The Market Pro subscription and the caller is on the free tier", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "requires_pro" ] } } } } } ] } } } }, "403": { "description": "`email_unverified` -- the account that owns the key has not verified its email address", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "email_unverified" ] } } } } } ] } } } }, "404": { "description": "`unknown_symbol` -- no such ticker; `not_covered` -- the symbol exists but is outside coverage; `no_analysis` -- the symbol is covered but has not been scored yet", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unknown_symbol", "not_covered", "no_analysis" ] } } } } } ] } } } }, "429": { "description": "`quota_exhausted` -- the free allowance is spent; upgrade or wait for the reset named in the message; `rate_limited` -- too many calls too quickly; wait the number of seconds in Retry-After", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "quota_exhausted", "rate_limited" ] } } } } } ] } } } }, "500": { "description": "`internal` -- the server failed to handle the request", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal" ] } } } } } ] } } } } } } }, "/api/v1/read_filing_section": { "post": { "operationId": "read_filing_section", "summary": "The text of one section of one filing, whole by default.", "description": "Returns the text of the section named by `section_id`, from either lane -- ids starting `note-` come from the notes lane, `item-` (or `whole-document`) from the narrative lane. THE WHOLE SECTION IS RETURNED BY DEFAULT: there is no token cap and no truncation you did not ask for. `total_chars` and `total_tokens` always describe the whole section, `chars` and `tokens` describe what came back, and `complete` says whether they are the same thing. `offset` and `limit` are opt-in; pages concatenate back into the section character for character. On a narrative section, read `section.confidence`, `section.flags` and `section.notice` before quoting -- a section flagged `incorporated_by_reference` is a pointer to another document, not the disclosure.\n\nRequires a Crush The Market API key; calls without one fail. Create an account and a key at https://crushthemarket.com/subscribe\n\nArguments may also be sent as a query string with `GET` on the same path. `POST` is documented because nested arguments (a screen's `criteria`, for instance) cannot be expressed in a query string.\n\nExamples:\n- `{\"symbol\":\"AAPL\",\"section_id\":\"note-income-taxes\"}` -- One whole note from EDGAR's own rendering.\n- `{\"symbol\":\"AAPL\",\"section_id\":\"item-1a\"}` -- Risk Factors from the primary document; check `section.confidence`.\n\nTool-specific failures:\n- `bad_request` -- `symbol` or `section_id` is missing, `section_id` belongs to neither lane, or `offset`/`limit` are not sane numbers.\n- `report_not_found` -- The notes lane has no section with that id in this filing; the message lists the ids it does have.\n- `section_not_found` -- The narrative lane has no section with that id in this filing.\n- `no_sections` -- The filing could not be sectioned at all, so no narrative id can be addressed. Use `whole-document`.\n- `edgar_unavailable` -- EDGAR did not answer after retries.\n\nRelated: `get_filing_outline`, `search_filing`, `score_evidence`.", "tags": [ "free" ], "requestBody": { "description": "The tool's arguments. An argument the tool does not declare is rejected, not ignored.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "The ticker as Crush The Market spells it.", "examples": [ "AAPL" ] }, "section_id": { "type": "string", "description": "A section id from get_filing_outline, e.g. `note-income-taxes` or `item-1a`.", "examples": [ "note-income-taxes" ] }, "accession": { "type": "string", "description": "A specific filing. Defaults to the latest annual report.", "examples": [ "0000320193-25-000079" ] }, "offset": { "type": "number", "description": "Opt-in pagination: start this many characters into the section. Omit for the whole thing.", "examples": [ 0 ] }, "limit": { "type": "number", "description": "Opt-in pagination: return at most this many characters. Omit for the whole section, which is the default and the recommended call.", "examples": [ 20000 ] } }, "additionalProperties": false, "required": [ "symbol", "section_id" ] }, "examples": { "example1": { "summary": "One whole note from EDGAR's own rendering.", "value": { "symbol": "AAPL", "section_id": "note-income-taxes" } }, "example2": { "summary": "Risk Factors from the primary document; check `section.confidence`.", "value": { "symbol": "AAPL", "section_id": "item-1a" } } } } } }, "responses": { "200": { "description": "The tool ran. A response carrying an `error` block never reaches this status -- a domain miss is mapped to its own status, so a 200 means a hit.", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Only these fields are emitted. Declared in the registry as `symbol`, `filing`, `lane`, `section`, `text`, `chars`, `tokens`, `total_chars`, `total_tokens`, `offset`, `limit`, `complete`, `truncated`, `page`, `pages_total`, `next_offset`, `is_last_page`, `token_estimate`, `note`, `error`, `as_of`, `source`, `disclaimer`, plus the provenance and quota block every response carries.", "properties": { "symbol": {}, "filing": {}, "lane": {}, "section": {}, "text": {}, "chars": {}, "tokens": {}, "total_chars": {}, "total_tokens": {}, "offset": {}, "limit": {}, "complete": {}, "truncated": {}, "page": {}, "pages_total": {}, "next_offset": {}, "is_last_page": {}, "token_estimate": {}, "note": {}, "error": { "description": "Present when the lookup missed. The call itself succeeded; see the status code." }, "as_of": {}, "source": {}, "disclaimer": {}, "quota": { "type": "object", "description": "The caller's agent-call allowance. `limit` is null on Pro, which is unmetered.", "properties": { "used": { "type": "integer" }, "limit": { "type": [ "integer", "null" ] }, "reset_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "notice": { "description": "Present only when the allowance is nearly spent." } } } } } }, "400": { "description": "`bad_request` -- the tool name is unknown, or an argument is missing, mistyped, or not one the tool declares (an undeclared argument is rejected, never ignored); `unknown_criterion` -- a criterion id is not one this API screens on", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "bad_request", "unknown_criterion" ] } } } } } ] } } } }, "401": { "description": "`missing_key` -- no API key was presented; `invalid_key` -- the key is unknown, malformed, or has been revoked", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "missing_key", "invalid_key" ] } } } } } ] } } } }, "402": { "description": "`requires_pro` -- the tool needs a Crush The Market Pro subscription and the caller is on the free tier", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "requires_pro" ] } } } } } ] } } } }, "403": { "description": "`email_unverified` -- the account that owns the key has not verified its email address", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "email_unverified" ] } } } } } ] } } } }, "404": { "description": "`unknown_symbol` -- no such ticker; `not_covered` -- the symbol exists but is outside coverage; `no_analysis` -- the symbol is covered but has not been scored yet", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unknown_symbol", "not_covered", "no_analysis" ] } } } } } ] } } } }, "429": { "description": "`quota_exhausted` -- the free allowance is spent; upgrade or wait for the reset named in the message; `rate_limited` -- too many calls too quickly; wait the number of seconds in Retry-After", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "quota_exhausted", "rate_limited" ] } } } } } ] } } } }, "500": { "description": "`internal` -- the server failed to handle the request", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal" ] } } } } } ] } } } } } } }, "/api/v1/search_filing": { "post": { "operationId": "search_filing", "summary": "Find a phrase across one filing, with the section each hit came from.", "description": "Literal, case-insensitive search across both lanes of one filing -- by default the latest annual report. Returns at most 10 hits, each about 400 characters of context and each tagged with the `section_id` it came from, so you can call read_filing_section and read the whole section rather than reasoning from a snippet. `total_matches` reports how many occurrences there were, so a returned list of ten is never mistaken for the complete set. A narrative hit carries the `confidence` and `notice` of the section it came from.\n\nRequires a Crush The Market API key; calls without one fail. Create an account and a key at https://crushthemarket.com/subscribe\n\nArguments may also be sent as a query string with `GET` on the same path. `POST` is documented because nested arguments (a screen's `criteria`, for instance) cannot be expressed in a query string.\n\nExamples:\n- `{\"symbol\":\"AAPL\",\"query\":\"effective tax rate\"}` -- Both lanes of Apple's latest 10-K.\n- `{\"symbol\":\"AAPL\",\"query\":\"goodwill\",\"lane\":\"notes\"}` -- Notes lane only -- cheaper, and the better lane for anything in the accounts.\n\nTool-specific failures:\n- `bad_request` -- `symbol` is missing, `query` is shorter than three characters, or `lane` is not one of notes/narrative/both.\n- `no_sec_filer` -- No SEC filer is mapped to the symbol.\n- `edgar_unavailable` -- Neither lane could be read from EDGAR.\n\nRelated: `get_filing_outline`, `read_filing_section`.", "tags": [ "free" ], "requestBody": { "description": "The tool's arguments. An argument the tool does not declare is rejected, not ignored.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "The ticker as Crush The Market spells it.", "examples": [ "AAPL" ] }, "query": { "type": "string", "description": "The phrase to find, at least 3 characters. Matched literally and case-insensitively.", "examples": [ "effective tax rate" ] }, "accession": { "type": "string", "description": "A specific filing. Defaults to the latest annual report.", "examples": [ "0000320193-25-000079" ] }, "lane": { "type": "string", "description": "Which lane to search: notes, narrative, or both. Defaults to both.", "examples": [ "notes" ] } }, "additionalProperties": false, "required": [ "symbol", "query" ] }, "examples": { "example1": { "summary": "Both lanes of Apple's latest 10-K.", "value": { "symbol": "AAPL", "query": "effective tax rate" } }, "example2": { "summary": "Notes lane only -- cheaper, and the better lane for anything in the accounts.", "value": { "symbol": "AAPL", "query": "goodwill", "lane": "notes" } } } } } }, "responses": { "200": { "description": "The tool ran. A response carrying an `error` block never reaches this status -- a domain miss is mapped to its own status, so a 200 means a hit.", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Only these fields are emitted. Declared in the registry as `symbol`, `filing`, `query`, `lane`, `sections_searched`, `total_matches`, `count`, `hits`, `note`, `error`, `as_of`, `source`, `disclaimer`, plus the provenance and quota block every response carries.", "properties": { "symbol": {}, "filing": {}, "query": {}, "lane": {}, "sections_searched": {}, "total_matches": {}, "count": {}, "hits": {}, "note": {}, "error": { "description": "Present when the lookup missed. The call itself succeeded; see the status code." }, "as_of": {}, "source": {}, "disclaimer": {}, "quota": { "type": "object", "description": "The caller's agent-call allowance. `limit` is null on Pro, which is unmetered.", "properties": { "used": { "type": "integer" }, "limit": { "type": [ "integer", "null" ] }, "reset_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "notice": { "description": "Present only when the allowance is nearly spent." } } } } } }, "400": { "description": "`bad_request` -- the tool name is unknown, or an argument is missing, mistyped, or not one the tool declares (an undeclared argument is rejected, never ignored); `unknown_criterion` -- a criterion id is not one this API screens on", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "bad_request", "unknown_criterion" ] } } } } } ] } } } }, "401": { "description": "`missing_key` -- no API key was presented; `invalid_key` -- the key is unknown, malformed, or has been revoked", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "missing_key", "invalid_key" ] } } } } } ] } } } }, "402": { "description": "`requires_pro` -- the tool needs a Crush The Market Pro subscription and the caller is on the free tier", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "requires_pro" ] } } } } } ] } } } }, "403": { "description": "`email_unverified` -- the account that owns the key has not verified its email address", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "email_unverified" ] } } } } } ] } } } }, "404": { "description": "`unknown_symbol` -- no such ticker; `not_covered` -- the symbol exists but is outside coverage; `no_analysis` -- the symbol is covered but has not been scored yet", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unknown_symbol", "not_covered", "no_analysis" ] } } } } } ] } } } }, "429": { "description": "`quota_exhausted` -- the free allowance is spent; upgrade or wait for the reset named in the message; `rate_limited` -- too many calls too quickly; wait the number of seconds in Retry-After", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "quota_exhausted", "rate_limited" ] } } } } } ] } } } }, "500": { "description": "`internal` -- the server failed to handle the request", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal" ] } } } } } ] } } } } } } }, "/api/v1/score_evidence": { "post": { "operationId": "score_evidence", "summary": "One score's legs, each paired with the notes in the company's own annual report that bear on it.", "description": "Takes one of the six scores and returns every leg that makes it up -- the leg, its weight or axis, its value where the scoring run stored one, and the stored measurements that feed it -- each paired with the note or notes from the company's own latest annual report whose subject covers that leg, quoted inline with a `section_id` for reading the whole note. THE TOOL DOES NOT ASSERT THAT THE TEXT EXPLAINS THE NUMBER: it states where the filer writes about the subject, and the inference is yours. A leg with no sensible note returns NO note and says why in `unmapped_because` -- a forced match would have you cite an irrelevant disclosure with total confidence. The quote is capped; `section_chars` is the whole note's size and read_filing_section returns it uncapped. Where a company has no SEC filing, the legs still come back and `note` says why nothing is quoted.\n\nRequires a Crush The Market API key; calls without one fail. Create an account and a key at https://crushthemarket.com/subscribe\n\nArguments may also be sent as a query string with `GET` on the same path. `POST` is documented because nested arguments (a screen's `criteria`, for instance) cannot be expressed in a query string.\n\nExamples:\n- `{\"symbol\":\"AAPL\",\"score\":\"management_score\"}` -- Four weighted legs; goodwill discipline pairs with the goodwill note, capital allocation with the equity note.\n- `{\"symbol\":\"AAPL\",\"score\":\"total_score\"}` -- Every leg is another composite, so every one is unmapped by construction and says so. Ask for the component score instead.\n\nTool-specific failures:\n- `bad_request` -- `symbol` is missing, or `score` is not one of the six score ids.\n- `unknown_symbol` -- No profile is held for the symbol at all.\n- `not_covered` -- The symbol is an ETF, which is never scored.\n- `no_analysis` -- The company is covered but has no scored row yet.\n\nRelated: `get_company`, `get_filing_outline`, `read_filing_section`.", "tags": [ "free" ], "requestBody": { "description": "The tool's arguments. An argument the tool does not declare is rejected, not ignored.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "The ticker as Crush The Market spells it.", "examples": [ "AAPL" ] }, "score": { "type": "string", "description": "Which score to break down. One of: value_score, growth_score, financial_score, dividend_score, management_score, total_score.", "examples": [ "management_score" ] }, "accession": { "type": "string", "description": "Take the notes from this filing rather than the latest annual report.", "examples": [ "0000320193-25-000079" ] } }, "additionalProperties": false, "required": [ "symbol", "score" ] }, "examples": { "example1": { "summary": "Four weighted legs; goodwill discipline pairs with the goodwill note, capital allocation with the equity note.", "value": { "symbol": "AAPL", "score": "management_score" } }, "example2": { "summary": "Every leg is another composite, so every one is unmapped by construction and says so. Ask for the component score instead.", "value": { "symbol": "AAPL", "score": "total_score" } } } } } }, "responses": { "200": { "description": "The tool ran. A response carrying an `error` block never reaches this status -- a domain miss is mapped to its own status, so a 200 means a hit.", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Only these fields are emitted. Declared in the registry as `symbol`, `score`, `score_label`, `score_value`, `score_column`, `filer_family`, `filing`, `legs`, `leg_count`, `legs_with_notes`, `legs_without_notes`, `quote_chars_max`, `token_estimate`, `note`, `error`, `as_of`, `source`, `disclaimer`, plus the provenance and quota block every response carries.", "properties": { "symbol": {}, "score": {}, "score_label": {}, "score_value": {}, "score_column": {}, "filer_family": {}, "filing": {}, "legs": {}, "leg_count": {}, "legs_with_notes": {}, "legs_without_notes": {}, "quote_chars_max": {}, "token_estimate": {}, "note": {}, "error": { "description": "Present when the lookup missed. The call itself succeeded; see the status code." }, "as_of": {}, "source": {}, "disclaimer": {}, "quota": { "type": "object", "description": "The caller's agent-call allowance. `limit` is null on Pro, which is unmetered.", "properties": { "used": { "type": "integer" }, "limit": { "type": [ "integer", "null" ] }, "reset_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "notice": { "description": "Present only when the allowance is nearly spent." } } } } } }, "400": { "description": "`bad_request` -- the tool name is unknown, or an argument is missing, mistyped, or not one the tool declares (an undeclared argument is rejected, never ignored); `unknown_criterion` -- a criterion id is not one this API screens on", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "bad_request", "unknown_criterion" ] } } } } } ] } } } }, "401": { "description": "`missing_key` -- no API key was presented; `invalid_key` -- the key is unknown, malformed, or has been revoked", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "missing_key", "invalid_key" ] } } } } } ] } } } }, "402": { "description": "`requires_pro` -- the tool needs a Crush The Market Pro subscription and the caller is on the free tier", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "requires_pro" ] } } } } } ] } } } }, "403": { "description": "`email_unverified` -- the account that owns the key has not verified its email address", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "email_unverified" ] } } } } } ] } } } }, "404": { "description": "`unknown_symbol` -- no such ticker; `not_covered` -- the symbol exists but is outside coverage; `no_analysis` -- the symbol is covered but has not been scored yet", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unknown_symbol", "not_covered", "no_analysis" ] } } } } } ] } } } }, "429": { "description": "`quota_exhausted` -- the free allowance is spent; upgrade or wait for the reset named in the message; `rate_limited` -- too many calls too quickly; wait the number of seconds in Retry-After", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "quota_exhausted", "rate_limited" ] } } } } } ] } } } }, "500": { "description": "`internal` -- the server failed to handle the request", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current burst window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the burst window refills.", "schema": { "type": "string", "format": "date-time" } }, "X-Quota-Used": { "description": "Agent calls spent in the current allowance window. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "The allowance for the window. Absent on Pro, which is unmetered.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Agent calls left in the allowance. Absent on Pro.", "schema": { "type": "integer" } }, "X-Quota-Reset": { "description": "When the allowance resets. Absent on Pro.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal" ] } } } } } ] } } } } } } } } }