Browse the extensions reference

Ingest Report

post/extensions/roboinvestor/{graph_id}/operations/ingest-report

Part 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-Key header.
  • Bearer token in the Authorization header.

Path parameters

NameTypeDescription
graph_idrequiredstringGraph Id

Constraints: matches ^(kg[a-f0-9]{16,}(?:_[a-zA-Z0-9]{1,20})?|sec(?:_[a-zA-Z0-9]{1,20})?|library)$

Header parameters

NameTypeDescription
Idempotency-KeyoptionalstringIdempotency-Key

Request body

Required, application/json.

FieldTypeDescription
entity_idrequiredstring

The entity the report is about (see create-issuer).

holonoptionalstring

The text of a .holon.jsonld report file.

Constraints: at most 26214400 characters

tavioptionalstring

The text of a .tavi.json compiled model. It is converted to a holon, which is what is stored.

Constraints: at most 26214400 characters

reportoptionalReportRowsInput

The report as rows.

ReportRowsInput fields
FieldTypeDescription
period_endrequiredstring (date)

The last day the report covers.

kindoptionalstring

What the report is, e.g. monthly-package, quarterly-financials. A later ingest for the same entity, period end and kind replaces this one.

Default: monthly-package

attributed_tooptionalstring

Who or what read the values out of the source document.

namespacesoptionalobject

Prefix to namespace URI, for concept prefixes that are not a library's.

conceptsoptionalReportConceptRow[]

The concepts the library does not have, each declared once. A library concept (rs-gaap:Assets) needs no entry unless the report words it differently.

Constraints: at most 750 items

ReportConceptRow fields
FieldTypeDescription
qnamerequiredstring

Prefixed name, e.g. rs-gaap:Assets for a library concept or kpi:Headcount for one of the firm's own. A prefix other than a library's must be bound in namespaces.

labeloptionalstring

The line's wording in the report.

kindoptionalstring

The value's type: monetary, shares, percent, pure, decimal, integer, string, text_block, date or boolean.

Default: monetary

period_typeoptionalstring

instant for a balance at a date, duration for a flow over a period.

balanceoptionalstring

debit or credit, when monetary.

abstractoptionalboolean

True for a heading that carries no value of its own.

Default: false

labelsoptionalobject

The document's own wording for a line, by library concept (rs-gaap:LaborAndRelatedExpense: Personnel Expense). The report reads back with this wording; the concept stays the library's.

sectionsoptionalReportSectionRow[]

The report's statements and tables.

Constraints: at most 50 items

ReportSectionRow fields
FieldTypeDescription
namerequiredstring

The section's title, e.g. Balance Sheet.

block_typeoptionalstring

balance_sheet, income_statement, cash_flow_statement or equity_statement for a primary statement; omit for any other table.

headoptionalstring

An abstract concept the section's top lines hang from. Required when a top line has nothing beneath it, as in a flat KPI table.

layoutoptionalstring

library lays a balance_sheet or an income_statement out from the library: every value sent for a concept the statement places becomes a line under the nearest line above it that also has a value, and each total is checked against the lines beneath it. given uses lines exactly as sent. Omitted, it is library when there are no lines and given when there are.

One of: library, given

linesoptionalReportLineRow[]

The lines, in order. With layout: library these are only the lines the library cannot place, or places differently than the document: a concept of the firm's own, each with the parent it sits under (a line of the statement that has a value) and its weight. A line given here replaces the library's placement of that concept.

Constraints: at most 500 items

factsrequiredReportFactRow[]

The values.

Constraints: 1–3000 items

ReportFactRow fields
FieldTypeDescription
conceptrequiredstring

The concept qname the value is for.

valuerequirednumber | string

The number, or the text for a non-numeric concept.

endrequiredstring (date)

The date the value is as of, or the last day of its period.

startoptionalstring (date)

The first day of the period; omit for a balance at a date.

unitoptionalstring

A currency code (USD), shares or pure. Required for a number.

decimalsoptionalinteger

Precision of the number: 0 to the unit, -3 to the thousand, 2 to the cent. Totals are checked to this precision.

sourceoptionalstring

Where the value was read from: the document, then #page=3 for a PDF or #sheet=BS&cell=B10 for a workbook, with &label= and the line's wording when useful. Kept on the fact.

nameoptionalstring

A display name for the report.

require_sourceoptionalboolean

Refuse the report unless every value names its source.

Default: false

dry_runoptionalboolean

Check the report and say what would load, without writing anything.

Default: false

Example request

curl
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

FieldTypeDescription
operationrequiredstring

Kebab-case operation name

operationIdrequiredstring

op_-prefixed ULID for audit and SSE correlation

statusrequiredstring

Operation lifecycle state

One of: completed, pending, failed

resultoptionalIngestReportResponse

Command-specific result payload

IngestReportResponse fields
FieldTypeDescription
dry_runrequiredboolean

True when nothing was written.

report_idoptionalstring

The report's ID in this graph; null on a dry run.

entity_idrequiredstring

The entity the report hangs on.

period_endrequiredstring (date)

The last day the report covers.

kindrequiredstring

What the report is.

fact_countrequiredinteger

Values loaded as facts.

section_countrequiredinteger

Statements and tables loaded.

calculations_checkedrequiredinteger

Totals that were compared with their terms; all agreed.

balance_checkedrequiredboolean

Whether total assets were compared with liabilities and equity.

concepts_addedoptionalstring[]

Concepts the graph did not have, added to its received-reports vocabulary.

dimensional_facts_not_loadedoptionalinteger

Values broken out by a dimension. They stay in the stored file; the graph holds the report's totals.

Default: 0

replaced_report_idsoptionalstring[]

Earlier ingests for the same entity, period end and kind, now replaced.

unplaced_conceptsoptionalstring[]

Library concepts with a value that no section places, for a report sent as rows. Their values load, but appear on no statement or table.

conforms_to_libraryoptionalboolean

For a report sent as rows: true when its balance sheet and income statement are arranged as the library arranges them, so their lines mean what the same lines mean in any other report. Null for a holon or a Tavi model, which is not compared.

departuresoptionalReportDeparture[]

Each place the report departs from the library's arrangement. The report still loads; the list is kept with it.

ReportDeparture fields
FieldTypeDescription
sectionrequiredstring

The section it is in.

kindrequiredstring

moved: a library concept sits under a different line, or with a different sign, than the library gives it. placed: a library concept the library does not put on this statement was given a line. own_subtotal: a concept of the firm's own has library concepts beneath it. own_layout: the whole statement came with its own lines.

One of: moved, placed, own_subtotal, own_layout

conceptoptionalstring

The concept, when it is about one.

library_parentoptionalstring

For moved: the line the library puts it under.

parentoptionalstring

The line the report puts it under.

detailrequiredstring

The departure as a sentence.

atrequiredstring

ISO-8601 UTC timestamp

createdByoptionalstring

User ID that initiated the operation

idempotentReplayoptionalboolean

True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.

Default: false

StatusMeaning
400Invalid request
401Authentication required
403Access denied
404Resource not found
409Idempotency-Key conflict — key reused with different body
422Validation error
429Rate limit exceeded
500Internal server error