Positions API
API reference for Position Object CRUD operations.
POST /v1/positions/
Register a new Position Object in the registry.
Request
The body must conform to the Position Object schema. Required fields: entity_id, owner, asset, status.
{
"entity_id": "pos-meg-2026-001",
"owner": "part-gp-a",
"status": "active",
"asset": {
"vehicle_class": "doiv_gp_interest",
"fund": "megalith-frontier-2026",
"issuer": { "name": "AV R&D Saronic, LLC", "jurisdiction": "US-DE" },
"underlying": { "company": "Saronic Technologies" }
},
"economic_rights": {
"carry": { "gp_rate": 0.05 },
"distributions": "pro_rata"
},
"transfer": {
"transferable": true,
"restrictions": [
{ "type": "consent_required" },
{ "type": "itar_restriction" }
]
}
}Response (201)
Returns the created Position Object.
GET /v1/positions/:id
Retrieve a Position Object by ID.
Response
{
"entity_id": "pos-meg-2026-001",
"owner": "part-gp-a",
"status": "active",
"asset": { ... },
"economic_rights": { ... },
"valuation": {
"current_mark": { "value": "12000000", "currency": "USD", "as_of": "2026-03-20" }
},
"transfer": { ... },
"compliance": { "itar_sensitive": true, "cfius_covered": false }
}Returns 404 if the position does not exist.
GET /v1/positions/:id/events
Retrieve the event history for a position. Events are returned in chronological order.
Response
[
{
"event_id": "evt-001",
"position_id": "pos-meg-2026-001",
"type": "position.registered",
"actor": "system",
"timestamp": "2026-03-20T10:00:00Z",
"payload": { "entity_id": "pos-meg-2026-001" }
},
{
"event_id": "evt-002",
"position_id": "pos-meg-2026-001",
"type": "position.updated",
"actor": "system",
"timestamp": "2026-03-20T11:00:00Z",
"payload": { "valuation": { "current_mark": { "value": "12000000" } } }
}
]PATCH /v1/positions/:id
Update fields on an existing Position Object. Commonly used for NAV mark updates and metadata changes. The entity_id cannot be changed.
Request
{
"valuation": {
"current_mark": { "value": "15000000", "currency": "USD", "as_of": "2026-03-25" }
},
"actor": "nav-update-service"
}Response
Returns the full updated Position Object. Returns 404 if the position does not exist.
POST /v1/positions/search
Search for positions matching filter criteria. Optionally pre-filters by transfer eligibility for a given requester.
Request
{
"filters": {
"vehicle_class": ["doiv_gp_interest", "doiv_lp_interest", "lp_interest"],
"transferable": true,
"underlying_company": "Saronic Technologies"
},
"requester": "part-buyer-001"
}When requester is provided, the response only includes positions that pass the Rights Engine evaluation for that buyer.
Response
{
"positions": [ ... ],
"count": 4
}