curl --request POST \
--url https://allocait.app/api/v1/scenarios/{id}/rules \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"dry_run": true,
"rules_text": "---\nversion: 1\nname: My rules\nclasses:\n Equities: { target: 47, min: 38, max: 56 }\n Fixed Income: { target: 21, min: 14, max: 29 }\n Commodities: { target: 9, min: 4, max: 13 }\n Cash: { min: 6, max: 19 }\n---\n\n# My rules\n\nIllustrative example. The figures are hypothetical, not a recommendation.\n"
}
'import requests
url = "https://allocait.app/api/v1/scenarios/{id}/rules"
payload = {
"dry_run": True,
"rules_text": "---
version: 1
name: My rules
classes:
Equities: { target: 47, min: 38, max: 56 }
Fixed Income: { target: 21, min: 14, max: 29 }
Commodities: { target: 9, min: 4, max: 13 }
Cash: { min: 6, max: 19 }
---
# My rules
Illustrative example. The figures are hypothetical, not a recommendation.
"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
dry_run: true,
rules_text: '---\nversion: 1\nname: My rules\nclasses:\n Equities: { target: 47, min: 38, max: 56 }\n Fixed Income: { target: 21, min: 14, max: 29 }\n Commodities: { target: 9, min: 4, max: 13 }\n Cash: { min: 6, max: 19 }\n---\n\n# My rules\n\nIllustrative example. The figures are hypothetical, not a recommendation.\n'
})
};
fetch('https://allocait.app/api/v1/scenarios/{id}/rules', 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://allocait.app/api/v1/scenarios/{id}/rules",
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([
'dry_run' => true,
'rules_text' => '---
version: 1
name: My rules
classes:
Equities: { target: 47, min: 38, max: 56 }
Fixed Income: { target: 21, min: 14, max: 29 }
Commodities: { target: 9, min: 4, max: 13 }
Cash: { min: 6, max: 19 }
---
# My rules
Illustrative example. The figures are hypothetical, not a recommendation.
'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$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://allocait.app/api/v1/scenarios/{id}/rules"
payload := strings.NewReader("{\n \"dry_run\": true,\n \"rules_text\": \"---\\nversion: 1\\nname: My rules\\nclasses:\\n Equities: { target: 47, min: 38, max: 56 }\\n Fixed Income: { target: 21, min: 14, max: 29 }\\n Commodities: { target: 9, min: 4, max: 13 }\\n Cash: { min: 6, max: 19 }\\n---\\n\\n# My rules\\n\\nIllustrative example. The figures are hypothetical, not a recommendation.\\n\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
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://allocait.app/api/v1/scenarios/{id}/rules")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"dry_run\": true,\n \"rules_text\": \"---\\nversion: 1\\nname: My rules\\nclasses:\\n Equities: { target: 47, min: 38, max: 56 }\\n Fixed Income: { target: 21, min: 14, max: 29 }\\n Commodities: { target: 9, min: 4, max: 13 }\\n Cash: { min: 6, max: 19 }\\n---\\n\\n# My rules\\n\\nIllustrative example. The figures are hypothetical, not a recommendation.\\n\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://allocait.app/api/v1/scenarios/{id}/rules")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"dry_run\": true,\n \"rules_text\": \"---\\nversion: 1\\nname: My rules\\nclasses:\\n Equities: { target: 47, min: 38, max: 56 }\\n Fixed Income: { target: 21, min: 14, max: 29 }\\n Commodities: { target: 9, min: 4, max: 13 }\\n Cash: { min: 6, max: 19 }\\n---\\n\\n# My rules\\n\\nIllustrative example. The figures are hypothetical, not a recommendation.\\n\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"scenario_id": "3f2e940e-c6d0-4710-ac50-7d981b4ef2dc",
"scenario_name": "My rules",
"dry_run": true,
"restore_point_id": null,
"classes_to_create": [],
"changes": [
{
"name": "Equities",
"asset_class_id": "d238ab31-0a5f-4a33-99e3-b828f2d4c316",
"change": "added",
"before": null,
"after": {
"target_allocation_pct": 47,
"min_position_pct": 38,
"max_position_pct": 56,
"size_min_pct": null,
"size_max_pct": null,
"short_size_min_pct": null,
"short_size_max_pct": null
},
"written_as": null
},
{
"name": "Fixed Income",
"asset_class_id": "768714f9-2f74-4712-ae2a-a8cff76267b0",
"change": "added",
"before": null,
"after": {
"target_allocation_pct": 21,
"min_position_pct": 14,
"max_position_pct": 29,
"size_min_pct": null,
"size_max_pct": null,
"short_size_min_pct": null,
"short_size_max_pct": null
},
"written_as": null
},
{
"name": "Commodities",
"asset_class_id": "a5abe5cf-9a5c-42e4-ad3c-f50ba87186fd",
"change": "added",
"before": null,
"after": {
"target_allocation_pct": 9,
"min_position_pct": 4,
"max_position_pct": 13,
"size_min_pct": null,
"size_max_pct": null,
"short_size_min_pct": null,
"short_size_max_pct": null
},
"written_as": null
},
{
"name": "Cash",
"asset_class_id": "38dc3624-7d8b-41d4-83c9-6162c0b99323",
"change": "added",
"before": null,
"after": {
"target_allocation_pct": null,
"min_position_pct": 6,
"max_position_pct": 19,
"size_min_pct": null,
"size_max_pct": null,
"short_size_min_pct": null,
"short_size_max_pct": null
},
"written_as": null
}
],
"counts": {
"added": 4,
"changed": 0,
"removed": 0,
"unchanged": 0
},
"issues": []
}{
"error": "Portfolio not found or access denied",
"error_code": "NOT_FOUND"
}{
"error": "Portfolio not found or access denied",
"error_code": "NOT_FOUND"
}{
"error": "Portfolio not found or access denied",
"error_code": "NOT_FOUND"
}{
"error": "Portfolio not found or access denied",
"error_code": "NOT_FOUND"
}{
"error": "Portfolio not found or access denied",
"error_code": "NOT_FOUND"
}{
"error": "Internal error",
"error_code": "INTERNAL_ERROR",
"request_id": "5b1e7c52-3f4a-4d0e-9a55-2d5cbe6f0a11"
}Import rules text into a scenario's rules, or preview it with dry_run
Parses rules_text with the same shared module the app and GET /rules/spec use, then reconciles the scenario’s rules to exactly
what it describes: the same absolute-state shape POST /scenarios/{id}/position-rules/apply uses, but by class NAME
rather than asset_class_id. Each name resolves server-side,
raw name first: an exact, case-insensitive match on the caller’s
own custom class, else a system class by that same raw name, else
(only when neither matches) a known alias (Stocks, Equity, ETFs, Funds ->
Equities; Bonds -> Fixed Income; Forex, FX ->
Currencies), else a new custom class named exactly as written. A
name matching an existing class is never renamed. Each entry in
changes carries written_as when the name in the file differs
from the resolved class’s own name. A class rule in the scenario
but not named in the file has its rule removed. Every import saves
a restore point of the scenario’s prior rules first, so it can be
undone with POST /rules/restore-points/{id}/restore.
Set dry_run: true to get the full preview (changes, counts,
classes_to_create) without writing anything or saving a restore
point; restore_point_id comes back null. dry_run: true
needs the API key to have the read permission; dry_run: false
(the default) needs write.
If the file has any error-level issue, nothing is parsed further
and nothing is written: the call fails 400 with error_code: RULES_INVALID and the full issues list, including every
warning. A file with only warnings applies normally and returns
those warnings in issues on the 200 response.
This states the user’s OWN thresholds back to Allocait, read from a file they wrote or approved. It never ranks, suggests, or opines on any security, and nothing here is a market call; see the note on this at the top of this document.
curl --request POST \
--url https://allocait.app/api/v1/scenarios/{id}/rules \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"dry_run": true,
"rules_text": "---\nversion: 1\nname: My rules\nclasses:\n Equities: { target: 47, min: 38, max: 56 }\n Fixed Income: { target: 21, min: 14, max: 29 }\n Commodities: { target: 9, min: 4, max: 13 }\n Cash: { min: 6, max: 19 }\n---\n\n# My rules\n\nIllustrative example. The figures are hypothetical, not a recommendation.\n"
}
'import requests
url = "https://allocait.app/api/v1/scenarios/{id}/rules"
payload = {
"dry_run": True,
"rules_text": "---
version: 1
name: My rules
classes:
Equities: { target: 47, min: 38, max: 56 }
Fixed Income: { target: 21, min: 14, max: 29 }
Commodities: { target: 9, min: 4, max: 13 }
Cash: { min: 6, max: 19 }
---
# My rules
Illustrative example. The figures are hypothetical, not a recommendation.
"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
dry_run: true,
rules_text: '---\nversion: 1\nname: My rules\nclasses:\n Equities: { target: 47, min: 38, max: 56 }\n Fixed Income: { target: 21, min: 14, max: 29 }\n Commodities: { target: 9, min: 4, max: 13 }\n Cash: { min: 6, max: 19 }\n---\n\n# My rules\n\nIllustrative example. The figures are hypothetical, not a recommendation.\n'
})
};
fetch('https://allocait.app/api/v1/scenarios/{id}/rules', 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://allocait.app/api/v1/scenarios/{id}/rules",
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([
'dry_run' => true,
'rules_text' => '---
version: 1
name: My rules
classes:
Equities: { target: 47, min: 38, max: 56 }
Fixed Income: { target: 21, min: 14, max: 29 }
Commodities: { target: 9, min: 4, max: 13 }
Cash: { min: 6, max: 19 }
---
# My rules
Illustrative example. The figures are hypothetical, not a recommendation.
'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$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://allocait.app/api/v1/scenarios/{id}/rules"
payload := strings.NewReader("{\n \"dry_run\": true,\n \"rules_text\": \"---\\nversion: 1\\nname: My rules\\nclasses:\\n Equities: { target: 47, min: 38, max: 56 }\\n Fixed Income: { target: 21, min: 14, max: 29 }\\n Commodities: { target: 9, min: 4, max: 13 }\\n Cash: { min: 6, max: 19 }\\n---\\n\\n# My rules\\n\\nIllustrative example. The figures are hypothetical, not a recommendation.\\n\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
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://allocait.app/api/v1/scenarios/{id}/rules")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"dry_run\": true,\n \"rules_text\": \"---\\nversion: 1\\nname: My rules\\nclasses:\\n Equities: { target: 47, min: 38, max: 56 }\\n Fixed Income: { target: 21, min: 14, max: 29 }\\n Commodities: { target: 9, min: 4, max: 13 }\\n Cash: { min: 6, max: 19 }\\n---\\n\\n# My rules\\n\\nIllustrative example. The figures are hypothetical, not a recommendation.\\n\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://allocait.app/api/v1/scenarios/{id}/rules")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"dry_run\": true,\n \"rules_text\": \"---\\nversion: 1\\nname: My rules\\nclasses:\\n Equities: { target: 47, min: 38, max: 56 }\\n Fixed Income: { target: 21, min: 14, max: 29 }\\n Commodities: { target: 9, min: 4, max: 13 }\\n Cash: { min: 6, max: 19 }\\n---\\n\\n# My rules\\n\\nIllustrative example. The figures are hypothetical, not a recommendation.\\n\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"scenario_id": "3f2e940e-c6d0-4710-ac50-7d981b4ef2dc",
"scenario_name": "My rules",
"dry_run": true,
"restore_point_id": null,
"classes_to_create": [],
"changes": [
{
"name": "Equities",
"asset_class_id": "d238ab31-0a5f-4a33-99e3-b828f2d4c316",
"change": "added",
"before": null,
"after": {
"target_allocation_pct": 47,
"min_position_pct": 38,
"max_position_pct": 56,
"size_min_pct": null,
"size_max_pct": null,
"short_size_min_pct": null,
"short_size_max_pct": null
},
"written_as": null
},
{
"name": "Fixed Income",
"asset_class_id": "768714f9-2f74-4712-ae2a-a8cff76267b0",
"change": "added",
"before": null,
"after": {
"target_allocation_pct": 21,
"min_position_pct": 14,
"max_position_pct": 29,
"size_min_pct": null,
"size_max_pct": null,
"short_size_min_pct": null,
"short_size_max_pct": null
},
"written_as": null
},
{
"name": "Commodities",
"asset_class_id": "a5abe5cf-9a5c-42e4-ad3c-f50ba87186fd",
"change": "added",
"before": null,
"after": {
"target_allocation_pct": 9,
"min_position_pct": 4,
"max_position_pct": 13,
"size_min_pct": null,
"size_max_pct": null,
"short_size_min_pct": null,
"short_size_max_pct": null
},
"written_as": null
},
{
"name": "Cash",
"asset_class_id": "38dc3624-7d8b-41d4-83c9-6162c0b99323",
"change": "added",
"before": null,
"after": {
"target_allocation_pct": null,
"min_position_pct": 6,
"max_position_pct": 19,
"size_min_pct": null,
"size_max_pct": null,
"short_size_min_pct": null,
"short_size_max_pct": null
},
"written_as": null
}
],
"counts": {
"added": 4,
"changed": 0,
"removed": 0,
"unchanged": 0
},
"issues": []
}{
"error": "Portfolio not found or access denied",
"error_code": "NOT_FOUND"
}{
"error": "Portfolio not found or access denied",
"error_code": "NOT_FOUND"
}{
"error": "Portfolio not found or access denied",
"error_code": "NOT_FOUND"
}{
"error": "Portfolio not found or access denied",
"error_code": "NOT_FOUND"
}{
"error": "Portfolio not found or access denied",
"error_code": "NOT_FOUND"
}{
"error": "Internal error",
"error_code": "INTERNAL_ERROR",
"request_id": "5b1e7c52-3f4a-4d0e-9a55-2d5cbe6f0a11"
}Authorizations
Raw API key shown once when created in the Allocait app (Settings > API keys). Send it verbatim in this header; the server stores and compares only its SHA-256 hash. Allocait generates every key: alc_ followed by 64 lowercase hex characters. Keys issued before 2026-10-10 are 64 hex characters with no prefix and keep working. A key may carry an expiry (90 days or 1 year, or never). A malformed, unknown, revoked or expired key gets 401 with no further detail, and a malformed one is refused before any lookup. Keys cannot be created through this API.
Path Parameters
scenario_id
Body
Response
The rules text was applied (or, under dry_run, previewed)
The result of an import (POST /scenarios/{id}/rules) or an undo
(POST /rules/restore-points/{id}/restore); both reconcile a
scenario's rules to an absolute desired state, the same shape
POST /scenarios/{id}/position-rules/apply uses, and both save a
restore point of what the scenario's rules were immediately before,
so either one can itself be undone.
Import only. True when nothing was written. changes and counts are still the full preview.
Null under dry_run: true. Otherwise the restore point saved
immediately before this write. Pass it to POST /rules/restore-points/{id}/restore to undo it.
Import only. Class names in the file that matched no existing class and will be (or, under dry_run, would be) created.
Ordered by file (or saved-snapshot) order for added/changed/unchanged, then by class display order for removed.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Import only. Warnings from reading the file; POST /scenarios/{id}/rules never reaches the RPC, and never returns this field, when the file has an error-level issue.
Show child attributes
Show child attributes
Restore only. Class names the saved rule pointed at that no longer exist or are no longer this key's to use. Restoring wrote nothing for these.
Restore only. Custom classes the original import created that nothing references any more, deleted as part of the undo.