> ## Documentation Index
> Fetch the complete documentation index at: https://docs.costory.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Enrichments API

> Upload, test, and publish Costory enrichment lookup files over HTTP. Store drafts, publish the set in one call, and trace a billed row before the next billing update.

The Enrichments API publishes the lookup files described in [Enrichments](/features/tagging/enrichments). One file reads a billing column and writes one or more business columns. You keep the files in git, upload each one as a draft, then publish the set. Authenticate with a bearer token as described in the [API overview](/api-reference/overview). Writes require an organization admin. Enrichments are in beta.

## Upload an enrichment

`PUT /enrichments/{name}` stores one document as a draft. The `{name}` in the path matches `name` in the body. Uploading the live document again clears its draft and the response is `unchanged`.

`DELETE /enrichments/{name}` drafts the removal of a live file. `DELETE /enrichments/draft` drops every pending draft. The live files stay as they are.

```bash theme={null}
curl -X PUT https://app-api.costory.io/enrichments/namespace_to_org \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "namespace_to_org",
    "keyField": "cos_namespace",
    "priority": 2,
    "targetColumns": [
      { "name": "owner_team", "mode": "merge" }
    ],
    "entries": [
      { "key": "payments", "then": { "owner_team": "Commerce" } }
    ]
  }'
```

The body is the JSON you keep in git. A `GET` of the live file is a valid upload body. [Enrichments](/features/tagging/enrichments) shows a static lookup, a static split, and a dynamic allocation from a BigQuery table. To publish the directory with Terraform, use the provider resources on that page.

[Get pending enrichment drafts](/api-reference/enrichments/get-enrichment-drafts) lists what would change and any reason the set would not compile.

## Publish enrichments

[Publish pending enrichment drafts](/api-reference/enrichments/publish-enrichment-drafts) compiles the live set with every draft applied. When the set compiles, Costory stores it in one step and starts a billing update. A set that does not compile is refused, and the live files stay as they are.

After publish, the output columns are available in [Explorer](/features/cost-explorer), dashboards, alerts, and reports, including history, on the next billing update.

## Trace one row

[List columns needed to trace a row](/api-reference/enrichments/list-enrichment-trace-inputs) returns the columns a test row needs. [Trace one row through the enrichments](/api-reference/enrichments/trace-an-enrichment-row) runs that row through the live files with the drafts applied, and returns each file's hit or miss.

```bash theme={null}
curl -X POST https://app-api.costory.io/enrichments/explain \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "row": {
      "cos_namespace": "payments",
      "cos_cluster_name": "prod"
    }
  }'
```

A dynamic allocation names the metric table. The shares appear after publish, on the next billing update. The same test is **Test enrichments** on the Dimensions page.

## Endpoints

* [List live enrichments](/api-reference/enrichments/list-live-enrichments)
* [Get one live enrichment document](/api-reference/enrichments/get-an-enrichment)
* [Store an enrichment document as a draft](/api-reference/enrichments/store-an-enrichment-draft)
* [Draft the removal of an enrichment](/api-reference/enrichments/draft-an-enrichment-removal)
* [Get pending enrichment drafts](/api-reference/enrichments/get-enrichment-drafts)
* [Discard pending enrichment drafts](/api-reference/enrichments/discard-enrichment-drafts)
* [Publish pending enrichment drafts](/api-reference/enrichments/publish-enrichment-drafts)
* [List columns needed to trace a row](/api-reference/enrichments/list-enrichment-trace-inputs)
* [Trace one row through the enrichments](/api-reference/enrichments/trace-an-enrichment-row)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.