curl --request POST \
--url https://allocait.app/api/v1/portfolios/{id}/positions/apply \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"positions": [
{
"symbol": "ALFA",
"shares": 250,
"asset_class_id": "d238ab31-0a5f-4a33-99e3-b828f2d4c316",
"current_price": 181.5
},
{
"symbol": "BRAV",
"shares": 200,
"asset_class_id": "768714f9-2f74-4712-ae2a-a8cff76267b0",
"current_price": 94.2
},
{
"symbol": "GOLF",
"shares": 300,
"asset_class_id": "a5abe5cf-9a5c-42e4-ad3c-f50ba87186fd",
"current_price": 62.3
}
]
}
'import requests
url = "https://allocait.app/api/v1/portfolios/{id}/positions/apply"
payload = { "positions": [
{
"symbol": "ALFA",
"shares": 250,
"asset_class_id": "d238ab31-0a5f-4a33-99e3-b828f2d4c316",
"current_price": 181.5
},
{
"symbol": "BRAV",
"shares": 200,
"asset_class_id": "768714f9-2f74-4712-ae2a-a8cff76267b0",
"current_price": 94.2
},
{
"symbol": "GOLF",
"shares": 300,
"asset_class_id": "a5abe5cf-9a5c-42e4-ad3c-f50ba87186fd",
"current_price": 62.3
}
] }
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({
positions: [
{
symbol: 'ALFA',
shares: 250,
asset_class_id: 'd238ab31-0a5f-4a33-99e3-b828f2d4c316',
current_price: 181.5
},
{
symbol: 'BRAV',
shares: 200,
asset_class_id: '768714f9-2f74-4712-ae2a-a8cff76267b0',
current_price: 94.2
},
{
symbol: 'GOLF',
shares: 300,
asset_class_id: 'a5abe5cf-9a5c-42e4-ad3c-f50ba87186fd',
current_price: 62.3
}
]
})
};
fetch('https://allocait.app/api/v1/portfolios/{id}/positions/apply', 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/portfolios/{id}/positions/apply",
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([
'positions' => [
[
'symbol' => 'ALFA',
'shares' => 250,
'asset_class_id' => 'd238ab31-0a5f-4a33-99e3-b828f2d4c316',
'current_price' => 181.5
],
[
'symbol' => 'BRAV',
'shares' => 200,
'asset_class_id' => '768714f9-2f74-4712-ae2a-a8cff76267b0',
'current_price' => 94.2
],
[
'symbol' => 'GOLF',
'shares' => 300,
'asset_class_id' => 'a5abe5cf-9a5c-42e4-ad3c-f50ba87186fd',
'current_price' => 62.3
]
]
]),
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/portfolios/{id}/positions/apply"
payload := strings.NewReader("{\n \"positions\": [\n {\n \"symbol\": \"ALFA\",\n \"shares\": 250,\n \"asset_class_id\": \"d238ab31-0a5f-4a33-99e3-b828f2d4c316\",\n \"current_price\": 181.5\n },\n {\n \"symbol\": \"BRAV\",\n \"shares\": 200,\n \"asset_class_id\": \"768714f9-2f74-4712-ae2a-a8cff76267b0\",\n \"current_price\": 94.2\n },\n {\n \"symbol\": \"GOLF\",\n \"shares\": 300,\n \"asset_class_id\": \"a5abe5cf-9a5c-42e4-ad3c-f50ba87186fd\",\n \"current_price\": 62.3\n }\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/portfolios/{id}/positions/apply")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"positions\": [\n {\n \"symbol\": \"ALFA\",\n \"shares\": 250,\n \"asset_class_id\": \"d238ab31-0a5f-4a33-99e3-b828f2d4c316\",\n \"current_price\": 181.5\n },\n {\n \"symbol\": \"BRAV\",\n \"shares\": 200,\n \"asset_class_id\": \"768714f9-2f74-4712-ae2a-a8cff76267b0\",\n \"current_price\": 94.2\n },\n {\n \"symbol\": \"GOLF\",\n \"shares\": 300,\n \"asset_class_id\": \"a5abe5cf-9a5c-42e4-ad3c-f50ba87186fd\",\n \"current_price\": 62.3\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://allocait.app/api/v1/portfolios/{id}/positions/apply")
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 \"positions\": [\n {\n \"symbol\": \"ALFA\",\n \"shares\": 250,\n \"asset_class_id\": \"d238ab31-0a5f-4a33-99e3-b828f2d4c316\",\n \"current_price\": 181.5\n },\n {\n \"symbol\": \"BRAV\",\n \"shares\": 200,\n \"asset_class_id\": \"768714f9-2f74-4712-ae2a-a8cff76267b0\",\n \"current_price\": 94.2\n },\n {\n \"symbol\": \"GOLF\",\n \"shares\": 300,\n \"asset_class_id\": \"a5abe5cf-9a5c-42e4-ad3c-f50ba87186fd\",\n \"current_price\": 62.3\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"portfolio_id": "919bbfb9-c2e7-4c4c-9d6d-d20f83330245",
"unchanged": [],
"mode": "replace",
"created": [
{
"symbol": "ALFA",
"shares": 250,
"result": {
"success": true,
"shares": 250,
"cash_impact": -45375,
"position_id": "3471983e-66bf-4b25-8cf6-5fd797a675e5",
"new_cash_balance": 54625
}
},
{
"symbol": "BRAV",
"shares": 200,
"result": {
"success": true,
"shares": 200,
"cash_impact": -18840,
"position_id": "b82535b6-a44d-4aad-b495-893a594e6a91",
"new_cash_balance": 35785
}
},
{
"symbol": "GOLF",
"shares": 300,
"result": {
"success": true,
"shares": 300,
"cash_impact": -18690,
"position_id": "60e31b17-793b-4efd-af47-30b29a3910e8",
"new_cash_balance": 17095
}
}
],
"updated": [],
"closed": [],
"action_ids": [
"6e3373d2-c862-4d52-8ef4-54a73ada4845",
"44df1d50-b26f-49d8-9934-3aae7d35abc9",
"9155bf83-aaa4-4b7c-99a0-3e0ebc23da80"
],
"unclassified": []
}{
"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": "Portfolio not found or access denied",
"error_code": "NOT_FOUND"
}{
"error": "Internal error",
"error_code": "INTERNAL_ERROR",
"request_id": "5b1e7c52-3f4a-4d0e-9a55-2d5cbe6f0a11"
}Reconcile a portfolio's holdings to an absolute desired state
“Make Allocait match what I hold”: the primary agent write (ADR-019). Pass the FULL desired set of non-cash holdings; anything currently held that is not listed is closed. Every change routes through the same RPC the app UI uses (position_create_with_cash/ position_update_with_cash/position_close), so cash is always settled and affordability always enforced server-side. This records the change in Allocait only. It moves no money and places no order.
Idempotent: calling this again with the same desired state changes
nothing (symbols already matching are reported under unchanged,
with no write performed). Atomic: the whole batch is one transaction;
if any single change would fail (e.g. insufficient cash), the
entire call fails and nothing from it is applied. A row whose share
count is unchanged needs no price, and a price on it is never used
for anything.
Shorts. A negative shares is a short. It is recorded only on a
portfolio with allow_shorts on and never for a holding in the
Options class (including a row that moves a short into Options);
otherwise the call is INVALID_INPUT, carries symbols, and writes
nothing. A short sale credits cash, and closing or reducing a short
debits it at the row’s current_price, so a cover that cash cannot
pay is INSUFFICIENT_CASH. A close of a held short (a shares: 0
row, or a held symbol you drop in replace mode) is that cover, and
needs its price like any close. Short proceeds are credited to cash
within the call, so one call can fund a buy with a short sale. A
repeat of the same desired state, shorts included, changes nothing.
Closing a symbol you drop from the desired state needs a price it
does not otherwise carry. price_overrides must carry one for every
held symbol absent from positions: its proceeds are booked at
that price. A held symbol about to close with no price in the map
fails with a 400 whose body carries missing_symbols. Allocait
never books a close at its own stored quote (ADR-036). An option you
leave out needs its price too, even with a mark: the mark may be
months old, and a close books cash at the price named. One case needs
none: an option past its expiry closes at 0 with no cash and records
one action (ADR-147).
Options and marks. A row may carry mark (an option’s per-share
premium; see DesiredPosition). Left out or null, the stored mark
stays. A row whose only change is mark is reported under updated,
needs no price, moves no cash and records no action. A mark on a
holding that ends outside the Options class is INVALID_INPUT, carries
symbols and writes nothing (ADR-147). An expired option is closed
with {symbol, shares: 0, price: 0}, after the person says what
happened; the row needs price: 0 because the share count changes.
Moves. A row may carry moves (1, 2, 3, -1, -2 or -3; see
DesiredPosition). Left out or null, the stored value stays, so the
state you read from GET /positions can go back unchanged. A row
whose only change is moves is reported under updated, needs no
price and records no action. Moves other than 1 on cash or on an
Options-class holding (including a row that moves a fund into
Options) is INVALID_INPUT and nothing is written (ADR-142).
Symbols. Every symbol is trimmed and uppercased before it is
matched, so alfa updates the held ALFA instead of opening a
second holding, and the close-price check uses the same rule. After
that each must be a ticker of 1 to 21 characters of A-Z, 0-9, . or
- starting with a letter or digit (ALFA, ALFA.B, or an option
symbol such as ECHO281215P00050000), or a slash pair
(ALFA/BRAV). Anything else is a 400 with “Each position needs a valid
symbol: a ticker (ALFA, ALFA.B) or a pair (ALFA/BRAV)”, and the database
refuses it with error_code: INVALID_INPUT if it gets that far.
Nothing is written.
Requires the API key to have the write permission.
curl --request POST \
--url https://allocait.app/api/v1/portfolios/{id}/positions/apply \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"positions": [
{
"symbol": "ALFA",
"shares": 250,
"asset_class_id": "d238ab31-0a5f-4a33-99e3-b828f2d4c316",
"current_price": 181.5
},
{
"symbol": "BRAV",
"shares": 200,
"asset_class_id": "768714f9-2f74-4712-ae2a-a8cff76267b0",
"current_price": 94.2
},
{
"symbol": "GOLF",
"shares": 300,
"asset_class_id": "a5abe5cf-9a5c-42e4-ad3c-f50ba87186fd",
"current_price": 62.3
}
]
}
'import requests
url = "https://allocait.app/api/v1/portfolios/{id}/positions/apply"
payload = { "positions": [
{
"symbol": "ALFA",
"shares": 250,
"asset_class_id": "d238ab31-0a5f-4a33-99e3-b828f2d4c316",
"current_price": 181.5
},
{
"symbol": "BRAV",
"shares": 200,
"asset_class_id": "768714f9-2f74-4712-ae2a-a8cff76267b0",
"current_price": 94.2
},
{
"symbol": "GOLF",
"shares": 300,
"asset_class_id": "a5abe5cf-9a5c-42e4-ad3c-f50ba87186fd",
"current_price": 62.3
}
] }
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({
positions: [
{
symbol: 'ALFA',
shares: 250,
asset_class_id: 'd238ab31-0a5f-4a33-99e3-b828f2d4c316',
current_price: 181.5
},
{
symbol: 'BRAV',
shares: 200,
asset_class_id: '768714f9-2f74-4712-ae2a-a8cff76267b0',
current_price: 94.2
},
{
symbol: 'GOLF',
shares: 300,
asset_class_id: 'a5abe5cf-9a5c-42e4-ad3c-f50ba87186fd',
current_price: 62.3
}
]
})
};
fetch('https://allocait.app/api/v1/portfolios/{id}/positions/apply', 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/portfolios/{id}/positions/apply",
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([
'positions' => [
[
'symbol' => 'ALFA',
'shares' => 250,
'asset_class_id' => 'd238ab31-0a5f-4a33-99e3-b828f2d4c316',
'current_price' => 181.5
],
[
'symbol' => 'BRAV',
'shares' => 200,
'asset_class_id' => '768714f9-2f74-4712-ae2a-a8cff76267b0',
'current_price' => 94.2
],
[
'symbol' => 'GOLF',
'shares' => 300,
'asset_class_id' => 'a5abe5cf-9a5c-42e4-ad3c-f50ba87186fd',
'current_price' => 62.3
]
]
]),
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/portfolios/{id}/positions/apply"
payload := strings.NewReader("{\n \"positions\": [\n {\n \"symbol\": \"ALFA\",\n \"shares\": 250,\n \"asset_class_id\": \"d238ab31-0a5f-4a33-99e3-b828f2d4c316\",\n \"current_price\": 181.5\n },\n {\n \"symbol\": \"BRAV\",\n \"shares\": 200,\n \"asset_class_id\": \"768714f9-2f74-4712-ae2a-a8cff76267b0\",\n \"current_price\": 94.2\n },\n {\n \"symbol\": \"GOLF\",\n \"shares\": 300,\n \"asset_class_id\": \"a5abe5cf-9a5c-42e4-ad3c-f50ba87186fd\",\n \"current_price\": 62.3\n }\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/portfolios/{id}/positions/apply")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"positions\": [\n {\n \"symbol\": \"ALFA\",\n \"shares\": 250,\n \"asset_class_id\": \"d238ab31-0a5f-4a33-99e3-b828f2d4c316\",\n \"current_price\": 181.5\n },\n {\n \"symbol\": \"BRAV\",\n \"shares\": 200,\n \"asset_class_id\": \"768714f9-2f74-4712-ae2a-a8cff76267b0\",\n \"current_price\": 94.2\n },\n {\n \"symbol\": \"GOLF\",\n \"shares\": 300,\n \"asset_class_id\": \"a5abe5cf-9a5c-42e4-ad3c-f50ba87186fd\",\n \"current_price\": 62.3\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://allocait.app/api/v1/portfolios/{id}/positions/apply")
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 \"positions\": [\n {\n \"symbol\": \"ALFA\",\n \"shares\": 250,\n \"asset_class_id\": \"d238ab31-0a5f-4a33-99e3-b828f2d4c316\",\n \"current_price\": 181.5\n },\n {\n \"symbol\": \"BRAV\",\n \"shares\": 200,\n \"asset_class_id\": \"768714f9-2f74-4712-ae2a-a8cff76267b0\",\n \"current_price\": 94.2\n },\n {\n \"symbol\": \"GOLF\",\n \"shares\": 300,\n \"asset_class_id\": \"a5abe5cf-9a5c-42e4-ad3c-f50ba87186fd\",\n \"current_price\": 62.3\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"portfolio_id": "919bbfb9-c2e7-4c4c-9d6d-d20f83330245",
"unchanged": [],
"mode": "replace",
"created": [
{
"symbol": "ALFA",
"shares": 250,
"result": {
"success": true,
"shares": 250,
"cash_impact": -45375,
"position_id": "3471983e-66bf-4b25-8cf6-5fd797a675e5",
"new_cash_balance": 54625
}
},
{
"symbol": "BRAV",
"shares": 200,
"result": {
"success": true,
"shares": 200,
"cash_impact": -18840,
"position_id": "b82535b6-a44d-4aad-b495-893a594e6a91",
"new_cash_balance": 35785
}
},
{
"symbol": "GOLF",
"shares": 300,
"result": {
"success": true,
"shares": 300,
"cash_impact": -18690,
"position_id": "60e31b17-793b-4efd-af47-30b29a3910e8",
"new_cash_balance": 17095
}
}
],
"updated": [],
"closed": [],
"action_ids": [
"6e3373d2-c862-4d52-8ef4-54a73ada4845",
"44df1d50-b26f-49d8-9934-3aae7d35abc9",
"9155bf83-aaa4-4b7c-99a0-3e0ebc23da80"
],
"unclassified": []
}{
"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": "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
portfolio_id
Body
The full desired set of non-cash holdings.
Show child attributes
Show child attributes
Symbol-to-price map. Keys are ticker symbols, matched
case-insensitively (normalised to uppercase); values are numbers,
0 or more. 0 is a real price, for example an option that expired
worthless. On the agent surface, a symbol you leave out of this map is
never priced from Allocait's own data (ADR-036); it comes back
null, or the call is refused, depending on the endpoint. Two
exceptions are the user's own numbers, not Allocait's: a held option
with a mark is priced at its mark, so you may leave it out, and a
price you pass for it replaces the mark for that call only and is
never stored; an option past its expiry counts 0 whatever you pass
(ADR-147).
Show child attributes
Show child attributes
{ "ALFA": 181.5, "ECHO": 98.1, "GOLF": 62.3 }
Response
Reconciliation result
Share changes, plus class, sizing and Moves changes on an unchanged
share count as {symbol, shares, asset_class_id, sizing}.
Holdings taken to 0 shares. Closing a short is a cover, which debits cash; read the sign of the change in shares, not the word, to tell which way cash moved.
Symbols already matching the desired state, shares and class. No RPC call was made for these.
The actions this call recorded, for PATCH /actions/{id} to add a comment later.
Holdings left with no asset class. No band judges them until they have one.