RoboLedger: Taxonomy & Mapping

Create Mapping Association

Link a chart-of-accounts element to a US GAAP reporting concept. One mapping edge per call — use auto-map-elements for bulk AI-assisted mapping. Duplicate (from, to, type) tuples return 409. The target must be a leaf concept: a subtotal the statement sums from its children is refused (422). Map before you close: a new arc for an account with landed history in a closed month is refused (422), since the month's stamped statements were computed through the arcs as they stood. To move such an account, pass replaces_association_id (its current arc, removed in the same write). A move within the same primary statement is a reclassification and goes through: the stamped statements keep the answer as closed, live renders follow the new arc, and reclassified_periods names the months. A move across statements restates net income and is refused, naming the months to reopen latest-first.

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.

post/extensions/roboledger/{graph_id}/operations/create-mapping-association

Request

  • Base URL: https://api.robosystems.ai (the document declares no server; this is the origin it was published from)
  • URL: https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/create-mapping-association
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer

Path parameters

graph_idstring required

Headers

Idempotency-Keystring nullable

Request body

from_element_idstring required

Source element (typically a CoA element).

to_element_idstring required

Target element (typically a US GAAP reporting concept).

association_type'presentation' | 'calculation' | 'mapping' | 'equivalence'

Edge semantics. mapping rolls up CoA elements into reporting concepts; presentation orders concepts in a structure; calculation carries debit/credit weights; equivalence is a synonym link.

order_valuenumber nullable

Display order within the structure (lower = earlier).

weightnumber nullable

Calculation weight (typically +1.0 or -1.0). Used by calculation linkbases to express signed roll-ups.

confidencenumber nullable

Confidence score (0–1). For AI-suggested mappings: ≥0.90 auto-approved, 0.70–0.89 flagged for review, <0.70 skipped.

suggested_bystring nullable

Source of the suggestion (e.g., 'mapping_agent', 'user'). Captured for audit; not used by the runtime.

mapping_idstring required

Target mapping structure ID.

replaces_association_idstring nullable

The account's current mapping arc in this structure, removed in the same write: a remap in one call. When the account has landed history in a closed month the move is judged as a reclassification: allowed when the new concept sits on the same primary statement as the old one (the stamped statements keep the answer as closed; live renders follow the new arc; reclassified_periods names the months), refused when it crosses one.

reasonstring nullable

Why the account is reclassified. Recorded on the new arc beside the months it reaches.

Example request

{
  "association_type": "mapping",
  "confidence": 0.95,
  "from_element_id": "elem_coa_revenue_product",
  "mapping_id": "map_01HVF8T0M2YTAY3BBNRH0V0",
  "suggested_by": "user",
  "to_element_id": "elem_usgaap_Revenues",
  "weight": 1
}

Response

Successful Response

operationstring required

Kebab-case operation name

operationIdstring required

op_-prefixed ULID for audit and SSE correlation

status'completed' | 'pending' | 'failed' required

Operation lifecycle state

atstring required

ISO-8601 UTC timestamp

createdBystring nullable

User ID that initiated the operation

idempotentReplayboolean

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

Changes

No recorded changes to this operation across all 1 revision of this API.