Skip to main content

Planning API

The Planning API analyzes your current state and target goal, then produces actionable instructions. Three endpoints cover different planning needs.

POST /plan​

Returns ranked action suggestions based on structural comparison between current and goal states.

Request:

curl -X POST https://api.masar.almadar.io/plan \
  -H "Authorization: Bearer $MASAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "current": {"name": "App", "orbitals": []},
    "goal": {"name": "App", "orbitals": [{"entity": "Ticket", "traits": ["Triage"]}]},
    "domain": "helpdesk"
  }'

Response:

{
  "actions": [
    {"action": "add_entity", "params": {"name": "Ticket"}, "score": 0.97},
    {"action": "add_trait", "params": {"name": "Triage", "linkedEntity": "Ticket"}, "score": 0.95},
    {"action": "add_states", "params": {"trait": "Triage", "count": 4}, "score": 0.91}
  ],
  "total_actions": 3
}

POST /plan-instructions​

Returns fully parameterized, dependency-ordered instructions. This is the primary endpoint for agent-driven construction.

Request:

curl -X POST https://api.masar.almadar.io/plan-instructions \
  -H "Authorization: Bearer $MASAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "current": {"name": "App", "orbitals": []},
    "goal": "std-helpdesk",
    "domain": "helpdesk"
  }'

Response:

{
  "instructions": [
    {"level": 1, "action": "add_trait", "params": {"name": "TicketTriage", "linkedEntity": "Ticket"}},
    {"level": 2, "action": "add_states", "params": {"trait": "TicketTriage", "states": ["new", "assessing", "routed", "resolved"]}},
    {"level": 2, "action": "add_events", "params": {"trait": "TicketTriage", "events": ["ASSESS", "ROUTE", "RESOLVE"]}},
    {"level": 3, "action": "add_transitions", "params": {"trait": "TicketTriage", "transitions": [{"from": "new", "event": "ASSESS", "to": "assessing"}]}}
  ],
  "levels": 7,
  "total_instructions": 14
}

Instructions at the same level can be executed in parallel. Instructions at level N depend on level N-1 being complete.

POST /gap​

Identifies structural differences between two schemas. Useful for understanding what's missing or what changed.

Request:

curl -X POST https://api.masar.almadar.io/gap \
  -H "Authorization: Bearer $MASAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {"name": "App", "orbitals": [{"entity": "Ticket"}]},
    "target": "std-helpdesk"
  }'

Response:

{
  "missing": [
    {"type": "trait", "name": "TicketTriage", "linkedEntity": "Ticket"},
    {"type": "page", "name": "Dashboard", "route": "/dashboard"}
  ],
  "extra": [],
  "modified": [],
  "gap_score": 0.72
}

The gap_score ranges from 0.0 (identical) to 1.0 (completely different).

Next Steps​