Ingest Report
/extensions/roboinvestor/{graph_id}/operations/ingest-reportPart of RoboInvestor.
Load a report a company sent onto its entity. Give the report as holon (the text of a .holon.jsonld file), as tavi (the text of a .tavi.json compiled model) or as report (rows read from a PDF or a workbook: each value with the page or cell it came from). Rows and a Tavi model are turned into a holon here. For rows, a balance sheet or an income statement named without its lines is laid out from the library, so only the values need sending. The holon is checked before anything is written: every value resolves, duplicate values agree, every total foots to its terms, and total assets equal total liabilities and equity. A report that fails is refused with each reason and nothing is loaded. One that passes is stored as the record of what was received, and its facts become queryable from every holding in the company. A second ingest for the same entity, period end and kind replaces the first. Set dry_run to run the checks and see what would load without writing.
Idempotency: supply an Idempotency-Key header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.
Authentication
Authenticate in any one of these ways — not all of them:
- API key in the
X-API-Keyheader. - Bearer token in the
Authorizationheader.
Path parameters
| Name | Type | Description |
|---|---|---|
graph_idrequired | string | Graph Id Constraints: matches |
Header parameters
| Name | Type | Description |
|---|---|---|
Idempotency-Keyoptional | string | Idempotency-Key |
Request body
Required, application/json.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
entity_idrequired | string | The entity the report is about (see | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
holonoptional | string | The text of a Constraints: at most 26214400 characters | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
tavioptional | string | The text of a Constraints: at most 26214400 characters | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
reportoptional | ReportRowsInput | The report as rows. ReportRowsInput fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nameoptional | string | A display name for the report. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
require_sourceoptional | boolean | Refuse the report unless every value names its source. Default: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
dry_runoptional | boolean | Check the report and say what would load, without writing anything. Default: |
Example request
curl -X POST "https://api.robosystems.ai/extensions/roboinvestor/{graph_id}/operations/ingest-report" \
-H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
-H "Idempotency-Key: <Idempotency-Key>" \
-H "Content-Type: application/json" \
-d '{
"entity_id": "string"
}'Responses
200 Successful Response
| Field | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
operationrequired | string | Kebab-case operation name | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
operationIdrequired | string | op_-prefixed ULID for audit and SSE correlation | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
statusrequired | string | Operation lifecycle state One of: | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
resultoptional | IngestReportResponse | Command-specific result payload IngestReportResponse fields
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
atrequired | string | ISO-8601 UTC timestamp | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdByoptional | string | User ID that initiated the operation | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
idempotentReplayoptional | boolean | True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions. Default: |
| Status | Meaning |
|---|---|
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Access denied |
| 404 | Resource not found |
| 409 | Idempotency-Key conflict — key reused with different body |
| 422 | Validation error |
| 429 | Rate limit exceeded |
| 500 | Internal server error |