# Resource Planning from the API or an agent

**Category:** [Resource Planning](https://help.totalctrl.app/hc/totalctrl/totalctrl-help-center/en-US/categories/resource-planning)
**Updated:** 2026-08-19

## REST

- `GET /api/v1/resourcing/allocations` — allocations overlapping a window. Filters: `user_id`, `project_id`, `include_soft`. Soft bookings are **excluded unless you ask for them**, which matches what “committed” means everywhere else in the app.

- `POST /api/v1/resourcing/allocations` — requires `user_id`, `project_id`, `hours_per_week`, `start_date`, `end_date`; optional `is_soft` and `role_label`. Returns 201.

- `DELETE /api/v1/resourcing/allocations/<uid>`

- `GET /api/v1/resourcing/availability` — per person over the window: available, allocated, logged and billable hours, plus utilization and allocation percentages.

## Windows: `from`, `to`, and a 26-week cap

Both read endpoints take `from` and `to` as `YYYY-MM-DD` and default to the next four weeks. A window is capped at 26 weeks, matching the pages — beyond half a year the answer is a forecast, not a plan.

## Read `basis`

The availability response carries `basis`: `available` (capacity less approved leave) or `capacity` (leave ignored). This is part of the contract, not diagnostics. 68% against available hours and 68% against raw capacity are different claims about a person, and nothing in the number tells you which one you were handed.

## Null is not zero

`utilization_pct` and `allocated_pct` come back `null` when there were no available hours to divide by. Rendering that as 0% reports somebody who was on leave for the whole window as completely idle. Show a dash, or leave the cell out.

## MCP tools

- `resourcing_availability` — availability and utilization per person over a range, returning the basis with it.

- `resourcing_find_available` — who has spare hours, most free first; optional `min_free_hours` and `skill` (the skill filter needs the Employee Directory).

- `resourcing_allocate` — book somebody onto a project. Set `is_soft` for a tentative booking, which stays out of their committed total.

## Webhooks

- `resourcing.allocation.created` and `resourcing.allocation.deleted`

- `resourcing.time_off.created` and `resourcing.time_off.deleted`

- `resourcing.profile.updated` — somebody's capacity or working pattern changed

Allocations created through the API and through an agent fire the same events as the ones created on the grid.

## No model is in this path

Every figure these endpoints return is arithmetic over stored rows. Nothing here calls an LLM, so nothing here spends AI Units — poll it as often as you like.

---

## Related Articles

- [Availability and utilization: which number you are actually looking at](https://help.totalctrl.app/en-US/articles/resource-planning-utilization)
- [Capacity, working patterns and time off](https://help.totalctrl.app/en-US/articles/resource-planning-capacity-and-leave)
- [Who can see and change what, including contractors](https://help.totalctrl.app/en-US/articles/resource-planning-access)
- [What Resource Planning is, and what it deliberately does not do](https://help.totalctrl.app/en-US/articles/resource-planning-overview)
- [Allocations: hours a week, soft bookings and overlaps](https://help.totalctrl.app/en-US/articles/resource-planning-allocations)

---
[← Back to TotalCtrl Help Center](https://help.totalctrl.app/en-US/)