---
title: "Link Entity to Taxonomy"
method: POST
path: "/extensions/roboledger/{graph_id}/operations/link-entity-taxonomy"
tags: ["RoboLedger: Taxonomy & Mapping"]
---

# Link Entity to Taxonomy

`POST /extensions/roboledger/{graph_id}/operations/link-entity-taxonomy`

## 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/link-entity-taxonomy`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Link an entity to a taxonomy. Idempotent — returns the existing linkage if it already exists. CoA blocks auto-link at create time; use this to switch an entity's primary chart of accounts. Only the `chart_of_accounts` basis changes behavior: a `reporting`, `mapping` or `schedule` link records the association and nothing reads it. Statements render from the entity's reporting style (change-reporting-style), and custom statement rows come from a reporting extension of that style.

**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.

## Path parameters

- `graph_id` string, required

## Headers

- `Idempotency-Key` string, nullable

## Request body

- LinkEntityTaxonomyRequest: Link an entity to a taxonomy (creates the ENTITY_HAS_TAXONOMY edge). A `chart_of_accounts` link tells the platform which chart the entity keeps its books in; CoA blocks auto-link at create time, so use this to switch the primary one. The other bases record the association and nothing reads them: statements render from the entity's reporting style, whatever taxonomy is linked. Idempotent — re-linking returns the existing edge unchanged.
  - `entity_id` string, nullable: The entity to link, by id. Omit for the group parent.
  - `taxonomy_id` string, required: The taxonomy to link to.
  - `basis` 'reporting' | 'chart_of_accounts' | 'mapping' | 'schedule': Linkage role: `chart_of_accounts` (the entity's CoA), `reporting` (a reporting standard), `mapping` (CoA→reporting rollup), `schedule` (schedule structure). Only `chart_of_accounts` is read; the others are recorded and do not change how statements render.
  - `is_primary` boolean: Mark this as the primary linkage for the basis. False allows secondary attachments (e.g. parallel reporting standards).
  - `adoption_context` string, nullable: Why the entity is reporting under this taxonomy (e.g. 'voluntary', 'regulatory', 'lender_requirement').

## Response `200`

Successful Response

- OperationEnvelopeEntityTaxonomyResponse
  - `operation` string, required: Kebab-case operation name
  - `operationId` string, required: op_-prefixed ULID for audit and SSE correlation
  - `status` 'completed' | 'pending' | 'failed', required: Operation lifecycle state
  - `result` EntityTaxonomyResponse: Result of `link-entity-taxonomy` — the ENTITY_HAS_TAXONOMY edge.
    - `entity_id` string, required: The entity that was linked.
    - `taxonomy_id` string, required: The taxonomy that was linked.
    - `basis` string, required: Linkage role (see request).
    - `is_primary` boolean, required: Whether this is the primary linkage.
    - `adoption_context` string, nullable: Adoption context recorded at link time.
  - `at` string, required: ISO-8601 UTC timestamp
  - `createdBy` string, nullable: User ID that initiated the operation
  - `idempotentReplay` boolean: True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.

## Other responses

- `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

---

[API](https://skmtc.dev/robosystems/apis/robosystems-api.md) · [All operations](https://skmtc.dev/robosystems/apis/robosystems-api/llms.txt) · [OpenAPI document](https://skmtc.dev/robosystems/apis/robosystems-api/revisions/e661e2d5ca6a?raw)