Skip to main content
POST
/
api
/
v1
/
context
/
dimensions
Create a dimension context item
curl --request POST \
  --url https://api.staging.getmodus.com/api/v1/context/dimensions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "customer_country",
  "description": "ISO 3166 country code from billing address.",
  "expr": "${customers.billing_country}",
  "dataType": "TEXT"
}
'
{
  "contextItemId": "7a3f9d2c-1111-4000-a000-000000000abc",
  "kind": "note",
  "s3Key": "context_notes/7a3f9d2c.../Q3_churn_analysis.md",
  "title": "Q3 churn analysis"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
name
string
required

Dimension name.

Example:

"customer_country"

​
description
string
required

Human description.

Example:

"ISO 3166 country code derived from billing address."

​
expr
string
required

Semantic-layer expression (varies by data warehouse).

Example:

"${customers.billing_country}"

​
dataType
string
default:TEXT

Data type tag. Defaults to TEXT.

Example:

"TEXT"

​
synonyms
string[]

Optional synonyms used for fuzzy matching.

Example:
["country", "nation"]
​
unique
boolean

True if values are unique per row.

Example:

false

​
sampleValues
string

Optional comma- or newline-separated sample values for documentation.

Example:

"US, CA, GB, DE"

Response

​
contextItemId
string
required

UUID of the newly-created context item. Use it on subsequent GET / PATCH / DELETE calls.

Example:

"7a3f9d2c-1111-4000-a000-000000000abc"

​
kind
enum<string>
required

Kind of context item created.

Available options:
note,
saved_query,
link,
dimension,
fact,
metric,
filter
Example:

"note"

​
s3Key
string | null

Tenant S3 key for the raw content blob (notes, saved queries, links). Null for kinds without S3 backing.

Example:

"context_notes/7a3f9d2c.../Q3_churn_analysis.md"

​
title
string | null

Resolved title for the created item. Null for kinds without a title field.

Example:

"Q3 churn analysis"