curl --request POST \
--url https://{tenant}.earnie.dev/v1/policies \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"module": "<string>",
"category": "<string>",
"name": "<string>",
"expression": "<string>",
"parameter_spec": [
{
"key": "<string>",
"label": "<string>",
"options": [
"<string>"
],
"default": "<unknown>",
"constrains": "<string>"
}
],
"values": {},
"slug": "<string>",
"description": "<string>",
"agent_rule": "<string>",
"enabled": true,
"attach_project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'import requests
url = "https://{tenant}.earnie.dev/v1/policies"
payload = {
"module": "<string>",
"category": "<string>",
"name": "<string>",
"expression": "<string>",
"parameter_spec": [
{
"key": "<string>",
"label": "<string>",
"options": ["<string>"],
"default": "<unknown>",
"constrains": "<string>"
}
],
"values": {},
"slug": "<string>",
"description": "<string>",
"agent_rule": "<string>",
"enabled": True,
"attach_project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
module: '<string>',
category: '<string>',
name: '<string>',
expression: '<string>',
parameter_spec: [
{
key: '<string>',
label: '<string>',
options: ['<string>'],
default: '<unknown>',
constrains: '<string>'
}
],
values: {},
slug: '<string>',
description: '<string>',
agent_rule: '<string>',
enabled: true,
attach_project_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
})
};
fetch('https://{tenant}.earnie.dev/v1/policies', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{tenant}.earnie.dev/v1/policies",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'module' => '<string>',
'category' => '<string>',
'name' => '<string>',
'expression' => '<string>',
'parameter_spec' => [
[
'key' => '<string>',
'label' => '<string>',
'options' => [
'<string>'
],
'default' => '<unknown>',
'constrains' => '<string>'
]
],
'values' => [
],
'slug' => '<string>',
'description' => '<string>',
'agent_rule' => '<string>',
'enabled' => true,
'attach_project_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{tenant}.earnie.dev/v1/policies"
payload := strings.NewReader("{\n \"module\": \"<string>\",\n \"category\": \"<string>\",\n \"name\": \"<string>\",\n \"expression\": \"<string>\",\n \"parameter_spec\": [\n {\n \"key\": \"<string>\",\n \"label\": \"<string>\",\n \"options\": [\n \"<string>\"\n ],\n \"default\": \"<unknown>\",\n \"constrains\": \"<string>\"\n }\n ],\n \"values\": {},\n \"slug\": \"<string>\",\n \"description\": \"<string>\",\n \"agent_rule\": \"<string>\",\n \"enabled\": true,\n \"attach_project_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{tenant}.earnie.dev/v1/policies")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"module\": \"<string>\",\n \"category\": \"<string>\",\n \"name\": \"<string>\",\n \"expression\": \"<string>\",\n \"parameter_spec\": [\n {\n \"key\": \"<string>\",\n \"label\": \"<string>\",\n \"options\": [\n \"<string>\"\n ],\n \"default\": \"<unknown>\",\n \"constrains\": \"<string>\"\n }\n ],\n \"values\": {},\n \"slug\": \"<string>\",\n \"description\": \"<string>\",\n \"agent_rule\": \"<string>\",\n \"enabled\": true,\n \"attach_project_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{tenant}.earnie.dev/v1/policies")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"module\": \"<string>\",\n \"category\": \"<string>\",\n \"name\": \"<string>\",\n \"expression\": \"<string>\",\n \"parameter_spec\": [\n {\n \"key\": \"<string>\",\n \"label\": \"<string>\",\n \"options\": [\n \"<string>\"\n ],\n \"default\": \"<unknown>\",\n \"constrains\": \"<string>\"\n }\n ],\n \"values\": {},\n \"slug\": \"<string>\",\n \"description\": \"<string>\",\n \"agent_rule\": \"<string>\",\n \"enabled\": true,\n \"attach_project_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}"
response = http.request(request)
puts response.read_body{
"id": 123,
"slug": "<string>",
"source": "seed",
"module": "<string>",
"category": "<string>",
"name": "<string>",
"description": "<string>",
"agent_rule": "<string>",
"agent_rule_stale": true,
"enabled": true,
"action": "block",
"expression": "<string>",
"parameter_spec": [
{
"key": "<string>",
"label": "<string>",
"type": "string",
"options": [
"<string>"
],
"default": "<unknown>",
"constrains": "<string>"
}
],
"values": {},
"revision": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"result_summary": {
"state": "passed",
"violations_count": 1,
"affected_files_count": 1,
"affected_components_count": 1,
"missing_enrichments": [
"<string>"
],
"error_message": "<string>",
"last_evaluated_at": "2023-11-07T05:31:56Z"
}
}{
"code": "cel_compile",
"message": "<string>",
"position": 123
}{
"code": "<string>",
"message": "<string>"
}{
"code": "<string>",
"message": "<string>"
}{
"code": "slug_taken",
"slug": "<string>"
}{
"code": "unguarded_field",
"message": "<string>",
"path": "<string>",
"optional": true,
"position": 123
}Create a policy
Creates a new policy. The expression is compiled via cel-go before persistence; every params.X reference MUST resolve to a parameter_spec entry. Typical client flow: fetch the templates catalog via GET /v1/policies/templates, pick a seeded template, POST a body sourced from that row (the “Add from template” UX in the web client).
Supplying attach_project_id makes this one atomic create-and-attach: a 201 means the policy exists AND is attached to that project, and any failure leaves neither. There is no separate attach call to lose, and therefore no orphan definition to clean up — which matters because a policy is a shared organization-wide resource the client cannot delete on its own behalf.
Idempotency-Key makes the whole operation repeatable, which is what a retry after a lost response needs: without it, the retry creates a second shared definition.
curl --request POST \
--url https://{tenant}.earnie.dev/v1/policies \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"module": "<string>",
"category": "<string>",
"name": "<string>",
"expression": "<string>",
"parameter_spec": [
{
"key": "<string>",
"label": "<string>",
"options": [
"<string>"
],
"default": "<unknown>",
"constrains": "<string>"
}
],
"values": {},
"slug": "<string>",
"description": "<string>",
"agent_rule": "<string>",
"enabled": true,
"attach_project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'import requests
url = "https://{tenant}.earnie.dev/v1/policies"
payload = {
"module": "<string>",
"category": "<string>",
"name": "<string>",
"expression": "<string>",
"parameter_spec": [
{
"key": "<string>",
"label": "<string>",
"options": ["<string>"],
"default": "<unknown>",
"constrains": "<string>"
}
],
"values": {},
"slug": "<string>",
"description": "<string>",
"agent_rule": "<string>",
"enabled": True,
"attach_project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
module: '<string>',
category: '<string>',
name: '<string>',
expression: '<string>',
parameter_spec: [
{
key: '<string>',
label: '<string>',
options: ['<string>'],
default: '<unknown>',
constrains: '<string>'
}
],
values: {},
slug: '<string>',
description: '<string>',
agent_rule: '<string>',
enabled: true,
attach_project_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
})
};
fetch('https://{tenant}.earnie.dev/v1/policies', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{tenant}.earnie.dev/v1/policies",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'module' => '<string>',
'category' => '<string>',
'name' => '<string>',
'expression' => '<string>',
'parameter_spec' => [
[
'key' => '<string>',
'label' => '<string>',
'options' => [
'<string>'
],
'default' => '<unknown>',
'constrains' => '<string>'
]
],
'values' => [
],
'slug' => '<string>',
'description' => '<string>',
'agent_rule' => '<string>',
'enabled' => true,
'attach_project_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{tenant}.earnie.dev/v1/policies"
payload := strings.NewReader("{\n \"module\": \"<string>\",\n \"category\": \"<string>\",\n \"name\": \"<string>\",\n \"expression\": \"<string>\",\n \"parameter_spec\": [\n {\n \"key\": \"<string>\",\n \"label\": \"<string>\",\n \"options\": [\n \"<string>\"\n ],\n \"default\": \"<unknown>\",\n \"constrains\": \"<string>\"\n }\n ],\n \"values\": {},\n \"slug\": \"<string>\",\n \"description\": \"<string>\",\n \"agent_rule\": \"<string>\",\n \"enabled\": true,\n \"attach_project_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{tenant}.earnie.dev/v1/policies")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"module\": \"<string>\",\n \"category\": \"<string>\",\n \"name\": \"<string>\",\n \"expression\": \"<string>\",\n \"parameter_spec\": [\n {\n \"key\": \"<string>\",\n \"label\": \"<string>\",\n \"options\": [\n \"<string>\"\n ],\n \"default\": \"<unknown>\",\n \"constrains\": \"<string>\"\n }\n ],\n \"values\": {},\n \"slug\": \"<string>\",\n \"description\": \"<string>\",\n \"agent_rule\": \"<string>\",\n \"enabled\": true,\n \"attach_project_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{tenant}.earnie.dev/v1/policies")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"module\": \"<string>\",\n \"category\": \"<string>\",\n \"name\": \"<string>\",\n \"expression\": \"<string>\",\n \"parameter_spec\": [\n {\n \"key\": \"<string>\",\n \"label\": \"<string>\",\n \"options\": [\n \"<string>\"\n ],\n \"default\": \"<unknown>\",\n \"constrains\": \"<string>\"\n }\n ],\n \"values\": {},\n \"slug\": \"<string>\",\n \"description\": \"<string>\",\n \"agent_rule\": \"<string>\",\n \"enabled\": true,\n \"attach_project_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}"
response = http.request(request)
puts response.read_body{
"id": 123,
"slug": "<string>",
"source": "seed",
"module": "<string>",
"category": "<string>",
"name": "<string>",
"description": "<string>",
"agent_rule": "<string>",
"agent_rule_stale": true,
"enabled": true,
"action": "block",
"expression": "<string>",
"parameter_spec": [
{
"key": "<string>",
"label": "<string>",
"type": "string",
"options": [
"<string>"
],
"default": "<unknown>",
"constrains": "<string>"
}
],
"values": {},
"revision": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"result_summary": {
"state": "passed",
"violations_count": 1,
"affected_files_count": 1,
"affected_components_count": 1,
"missing_enrichments": [
"<string>"
],
"error_message": "<string>",
"last_evaluated_at": "2023-11-07T05:31:56Z"
}
}{
"code": "cel_compile",
"message": "<string>",
"position": 123
}{
"code": "<string>",
"message": "<string>"
}{
"code": "<string>",
"message": "<string>"
}{
"code": "slug_taken",
"slug": "<string>"
}{
"code": "unguarded_field",
"message": "<string>",
"path": "<string>",
"optional": true,
"position": 123
}Authorizations
An Earnie API key, sent as Authorization: Bearer sk_earnie_.... Create one under Settings > API keys. The key's scopes decide which operations it may call.
Headers
Opaque client-generated key. Repeating the same request with the same key and actor returns the originally created policy (201, no second policy); reusing the key for a DIFFERENT request returns 409 idempotency_conflict.
1 - 255Body
Enforcement action applied when the policy fires. Verdict mapping: block → block warn → warn require → require
block, warn, require Show child attributes
Show child attributes
Optional. When omitted, the server derives a slug from name (kebab-cased) and disambiguates collisions. Supply an explicit slug only when migrating known-identity rows.
The imperative sentence an AI coding agent reads instead of the CEL (see Policy.agent_rule). Optional; omitted means the rendering falls back to description.
Optional. When present, the created policy is attached to this project in the SAME transaction and authorization context as its creation — a failed attachment rolls the creation back rather than leaving an orphan definition behind.
Omit it for organization-level authoring, which stays valid for the consumers that deliberately want a definition with no attachment yet. The project must belong to the caller's organization; one that does not refuses the whole request before anything is written.
Response
Created
Stable, human-readable identifier safe across deploys and migrations. Generated from name (kebab-cased) on Create when not supplied; templates ship with deterministic slugs (e.g. block-copyleft-licenses). Immutable after creation.
Server-managed origin of the policy. Seeded templates return seed; user-authored rows return custom.
seed, custom Finding domain the policy targets (e.g. scans, crypto, crypto_finder). AI provenance is an xBOM enrichment, not a separate policy domain.
Grouping within a scanner (e.g. licenses, vulnerabilities).
Human-readable explanation of what the policy checks and why.
Keep it to roughly 200 bytes. That is not a stored-length limit — nothing rejects a longer one — it is where the RENDERED sentence is truncated with an ellipsis before it reaches an agent, measured after placeholders are substituted and in bytes rather than characters. A short rule whose {banned_licenses} expands to three hundred bytes is truncated too. The cap exists because this text sits in every prompt of every session.
Written in the second person, one sentence, no CEL: "Do not add dependencies licensed {banned_licenses}."
{key} placeholders name parameter_spec[].key entries and are substituted with the policy's current values at render time, so one sentence stays true after a parameter is tuned. A list value renders as a, b or c. A placeholder naming no parameter is rejected on save.
Empty is allowed and means "no agent rule": rendering falls back to description, and last to the CEL expression labelled as such, so a policy without one still reaches an agent. Like description it is prose and NOT part of the policy revision — rewording what an agent reads does not change what the gate does.
True when agent_rule was written against different rule logic than this policy now carries — its action, expression, or the set of parameter keys has changed since the sentence was last saved.
An agent rule is hand-written prose and cannot be derived from CEL, so nothing keeps it true when the expression moves underneath it. This is how the product notices: the sentence still renders (it is usually still mostly right), but the policy is flagged so a human can review it. Saving the agent rule again clears the flag.
Parameter VALUES are deliberately excluded: {key} placeholders already keep the sentence true across a retune, so a threshold tweak never raises this. False when the policy has no agent rule, and false for a row that predates the stored basis — "unknown" must not read as "stale".
Enforcement action applied when the policy fires. Verdict mapping: block → block warn → warn require → require
block, warn, require CEL string. Compiled via cel-go on save (parse + type check + params.X consistency) and evaluated against findings via Eval (see /preview for the live-evaluation surface).
Show child attributes
Show child attributes
Current parameter values keyed by parameter_spec[].key. Every declared key needs a value or a default in its spec entry, including a parameter the expression only reads behind has(); a key left out is stored with its default. See ValuesInvalidError.
The policy's immutable content revision: a sha256: digest over the canonical form of the gating content — action, expression, parameter_spec, values. It is byte-identical to the policy_hash an evaluation records and to the revision a scan's policy snapshot names, so "which revision produced this verdict" and "which revision is live now" are answered in one vocabulary.
Mutations echo it back in If-Match. A stale revision is 409 policy_conflict; a policy edit is never last-write-wins.
It covers the gating content and nothing else. Renaming a policy or rewriting its description leaves the revision unchanged, because neither changes what the gate does, and enabled is carried by presence in a scan's snapshot rather than by the digest.
Show child attributes
Show child attributes