Create Mapping Association

post/extensions/roboledger/{graph_id}/operations/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.

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

Name	Type	Description
`graph_id`required	string	Graph Id Constraints: matches `^(kg[a-f0-9]{16,}(?:_[a-zA-Z0-9]{1,20})?\|sec(?:_[a-zA-Z0-9]{1,20})?\|library)$`

Header parameters

Name	Type	Description
`Idempotency-Key`optional	string	Idempotency-Key

Request body

Required, application/json.

Field	Type	Description
`from_element_id`required	string	Source element (typically a CoA element).
`to_element_id`required	string	Target element (typically a US GAAP reporting concept).
`association_type`optional	string	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. One of: `presentation`, `calculation`, `mapping`, `equivalence` Default: `mapping`
`order_value`optional	number	Display order within the structure (lower = earlier).
`weight`optional	number	Calculation weight (typically +1.0 or -1.0). Used by calculation linkbases to express signed roll-ups.
`confidence`optional	number	Confidence score (0–1). For AI-suggested mappings: ≥0.90 auto-approved, 0.70–0.89 flagged for review, <0.70 skipped. Constraints: 0–1
`suggested_by`optional	string	Source of the suggestion (e.g., 'mapping_agent', 'user'). Captured for audit; not used by the runtime.
`mapping_id`required	string	Target mapping structure ID.
`replaces_association_id`optional	string	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.
`reason`optional	string	Why the account is reclassified. Recorded on the new arc beside the months it reaches. Constraints: at most 500 characters

Example request

curl · example 1 of 2

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/create-mapping-association" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "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
}'

curl · example 2 of 2

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/create-mapping-association" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "association_type": "mapping",
  "confidence": 0.92,
  "from_element_id": "elem_coa_returns_allowances",
  "mapping_id": "map_01HVF8T0M2YTAY3BBNRH0V0",
  "suggested_by": "mapping_agent",
  "to_element_id": "elem_usgaap_Revenues",
  "weight": -1
}'

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: completed, pending, failed

resultoptional

AssociationResponse

Command-specific result payload

AssociationResponse fields

Field	Type	Description
`id`required	string
`structure_id`required	string
`from_element_id`required	string
`from_element_name`optional	string
`from_element_qname`optional	string
`to_element_id`required	string
`to_element_name`optional	string
`to_element_qname`optional	string
`association_type`required	string
`order_value`optional	number
`weight`optional	number
`confidence`optional	number
`suggested_by`optional	string
`approved_by`optional	string
`replaced_association_id`optional	string	The arc this one replaced, when the write named one in `replaces_association_id`. On a read, set for an arc whose move reached a closed month.
`reclassified_periods`optional	string[]	Closed months whose live statements read through this arc while their stamped sets keep the answer as closed. Empty unless the arc replaced one on an account with landed history in a closed month.

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: false

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