Skip to main content
POST
/
api
/
v1
/
context
/
metrics
Create a metric context item
curl --request POST \
  --url https://api.staging.getmodus.com/api/v1/context/metrics \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "gross_margin_pct",
  "description": "Gross margin as a percentage of revenue.",
  "expr": "(${facts.revenue} - ${facts.cogs}) / ${facts.revenue}",
  "accessModifier": "public",
  "format": "percent"
}
'
{
  "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

Metric name.

Example:

"gross_margin_pct"

​
description
string
required

Human description.

Example:

"Gross margin as a percentage of revenue."

​
expr
string
required

Metric expression in the semantic layer.

Example:

"(${facts.revenue} - ${facts.cogs}) / ${facts.revenue}"

​
accessModifier
string
default:public

Access modifier (public / private). Defaults to public.

Example:

"public"

​
format
string

Display format hint (percent, currency, number, …).

Example:

"percent"

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"