Cite Concept

Join a registry-backed concept value to filing prose and optional extraction evidence.

Tier: paid | Cache: cache-only | Playground: authenticated only | Contract: 2.0.0

When To Use It

Use these tools when the model needs normalized financial facts, concept-level series, or statement-shaped outputs grounded in XBRL.

Request Examples


BASE_URL="${EDGAR_API_URL:-https://www.edgarparser.com}"
 
curl -sS "$BASE_URL/api/concept/cite" \
  -X POST \
  -H "Authorization: Bearer $EDGAR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"concept_name":"revenue","date_type":"Q","full_year_mode":false,"quarter":4,"source":"auto","ticker":"AAPL","year":2025}'


import os
import requests
 
base_url = os.getenv("EDGAR_API_URL", "https://www.edgarparser.com")
headers = {"Authorization": f"Bearer {os.environ['EDGAR_API_KEY']}"}
payload = {
  "concept_name": "revenue",
  "date_type": "Q",
  "full_year_mode": False,
  "quarter": 4,
  "source": "auto",
  "ticker": "AAPL",
  "year": 2025
}
 
response = requests.post(f"{base_url}/api/concept/cite", headers=headers, json=payload, timeout=30)
response.raise_for_status()
data = response.json()

Key Response Fields

Field	Type	Why It Matters
`status`	`const "success"`	Transport-level success indicator inside the JSON response.
`semantic_status`	`"ok" \| "partial" \| "empty" \| "error"`	Whether the response is semantically usable, partial, empty, or errored.
`coverage_status`	`"complete" \| "partial" \| "narrow" \| "none"`	Completeness signal; do not present partial or narrow coverage as complete.
`period`	`string`	Fiscal period associated with the returned value or filing.
`citations`	`array<object>`	Financial fact or concept field; inspect unit, period, and source context before using it.
`concept`	`object`	Financial fact or concept field; inspect unit, period, and source context before using it.
`concept_definition_version`	`integer`	Financial fact or concept field; inspect unit, period, and source context before using it.
`concept_name`	`string`	Financial fact or concept field; inspect unit, period, and source context before using it.

Response Fields To Inspect

status / semantic_status for whether the tool produced a usable fact set.
coverage_status and coverage_warning before treating the value as complete.
source_ref, concept names, units, and period metadata for citation and auditability.

Errors And Coverage

401 or 403: the API key is missing, expired, or not allowed to use this tier.
429: retry after the rate-limit window, and prefer broader batch or series tools over repeated single-period calls.
This tool is cache-only; if the target filing is not warm, warm it through an allowed paid path before retrying.
Paid or LLM-backed paths should be used only when cheaper fact, filing, table, or text tools cannot answer the question.
Treat partial coverage, empty arrays, and warning fields as answer-quality signals even when HTTP status is 200.

Concept, Filing Evidence, Filing Document

Generated Reference

Contract

Field	Value
Tool	`cite_concept`
Method	`POST`
Path	`/api/concept/cite`
Contract version	`2.0.0`

Parameters

Name	Location	Required	Type	Notes
none	-	-	-	-

Request Body Schema


{
  "additionalProperties": false,
  "properties": {
    "allow_stale_extractions": {
      "default": false,
      "type": "boolean"
    },
    "concept_name": {
      "type": "string"
    },
    "date_type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "full_year_mode": {
      "default": false,
      "type": "boolean"
    },
    "include_extractions": {
      "default": false,
      "type": "boolean"
    },
    "max_narrative_spans_per_source": {
      "default": 5,
      "maximum": 50.0,
      "minimum": 1.0,
      "type": "integer"
    },
    "narrative_sources": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "quarter": {
      "maximum": 4.0,
      "minimum": 1.0,
      "type": "integer"
    },
    "source": {
      "default": "auto",
      "type": "string"
    },
    "ticker": {
      "type": "string"
    },
    "year": {
      "type": "integer"
    }
  },
  "required": [
    "ticker",
    "year",
    "quarter",
    "concept_name"
  ],
  "type": "object"
}

Response Schema (200)


{
  "properties": {
    "citations": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "type": "array"
    },
    "concept": {
      "additionalProperties": true,
      "type": "object"
    },
    "concept_definition_version": {
      "type": "integer"
    },
    "concept_name": {
      "type": "string"
    },
    "concept_registry_version": {
      "type": "integer"
    },
    "coverage_status": {
      "enum": [
        "complete",
        "partial",
        "narrow",
        "none"
      ],
      "type": "string"
    },
    "date_type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "evidence_layers_consulted": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "extraction_schemas_used": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "full_year_mode": {
      "type": "boolean"
    },
    "narrative_sources_searched": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "narrative_status": {
      "enum": [
        "ok",
        "partial",
        "empty",
        "not_attempted"
      ],
      "type": "string"
    },
    "period": {
      "type": "string"
    },
    "quarter": {
      "type": "integer"
    },
    "registry_revision": {
      "type": "string"
    },
    "semantic_status": {
      "enum": [
        "ok",
        "partial",
        "empty",
        "error"
      ],
      "type": "string"
    },
    "source": {
      "enum": [
        "auto",
        "8k",
        "proxy",
        "20f",
        "6k"
      ],
      "type": "string"
    },
    "status": {
      "const": "success",
      "type": "string"
    },
    "ticker": {
      "type": "string"
    },
    "value_resolution": {
      "additionalProperties": true,
      "type": "object"
    },
    "year": {
      "type": "integer"
    }
  },
  "required": [
    "status",
    "ticker",
    "year",
    "quarter",
    "full_year_mode",
    "period",
    "source",
    "date_type",
    "concept_name",
    "concept_registry_version",
    "concept_definition_version",
    "registry_revision",
    "concept",
    "value_resolution",
    "narrative_status",
    "narrative_sources_searched",
    "evidence_layers_consulted",
    "extraction_schemas_used",
    "citations",
    "semantic_status",
    "coverage_status"
  ],
  "type": "object"
}