Estimates and plans
An estimate is what a described piece of work will cost: a probability distribution in US dollars with its median. Any signed-in person can ask. Accepting an estimate makes it the plan for its tag set; shares give each person their part of a project's plan.
| Endpoint | What it does | Who |
|---|---|---|
POST /estimates |
Ask the estimator for an estimate, or type one. | Any signed-in person; plan on the tag set when one is given |
GET /estimates |
The estimates you may view, newest first, each with whether it is the plan and the cost so far. | View on the tag set |
GET /estimates/{id} |
One estimate with the cost of its tag set and the labelled deviation. | View on the tag set |
POST /estimates/{id}/accept |
Make an estimate the plan for its tag set. | Plan on the tag set, in the web app |
GET /shares |
The shares in force whose project you may view. | View on the project |
POST /shares |
A person's share of a project's plan between two dates. | Plan on the project, in the web app |
Ask for an estimate
POST /api/v1/estimatesAuthorization: Bearer tc_cli_…
{ "work": "Checkout redesign: a new checkout flow with saved addresses and one-page payment", "tags": { "feature": "KD-1" }, "from": "2026-03-01", "to": "2026-03-31", "context": "The last checkout flow cost 702.40 USD, with sandbox timeouts"}| Field | Meaning |
|---|---|
work |
The description: a prompt, a spec, a feature or acceptance criteria. Required. |
tags |
The tag set the estimate is for. Optional: ask without one, keep it, and tag it later. |
from, to |
The work's date range. Default: today, and 30 days later. The plan is spread over these days. |
markup_percent |
Overhead inside the amount, such as 15. Optional. |
context |
Anything that helps the estimator, such as the summaries and cost of earlier work. Optional. |
median, distribution |
Type the estimate yourself instead of asking the classifier: the median in US dollars, and optionally the bands, which add up to 1. |
Each estimate is billed once, whatever the length of work and context, so send all the context you have. Without median, the hosted service's System 1 classifier answers from the description and the history of every tag value. A self-hosted instance without an estimator answers 409: send a median.
201 Created:
{ "id": "est_4k2q9w", "work": "Checkout redesign: a new checkout flow with saved addresses and one-page payment", "tags": { "feature": "KD-1" }, "currency": "USD", "median": "500.00", "distribution": [ { "up_to": "250.00", "p": "0.04" }, { "up_to": "500.00", "p": "0.46" }, { "up_to": "750.00", "p": "0.33" }, { "up_to": "1000.00", "p": "0.12" }, { "up_to": null, "p": "0.05" } ], "markup_percent": 0, "estimator": "classifier", "from": "2026-03-01", "to": "2026-03-31", "amount": "500.00", "accepted": false, "cost": null, "deviation": null, "deviation_label": null, "recorded_at": "2026-02-21T10:00:00Z"}median is the estimate; amount is the plan amount, the median with the markup inside: with markup_percent: 15 it would be 575.00. Each band of distribution is the chance p that the cost ends at or below up_to; the last band has no upper end. estimator is classifier, or the email of the person who typed it. cost is the cost of the tag set over the estimate's range so far, where the tag set has one; asked before March, KD-1 has none yet.
Read estimates
GET /estimates/{id} returns the same shape with today's figures. Once accepted, deviation is plan minus cost, positive favourable, and deviation_label is scope, trouble or estimate_itself from the classifier, as on Deviation and forecast. For KD-1 as of 5 April: amount "500.00", cost "580.00", deviation "-80.00", deviation_label "scope".
GET /estimates?as_of=2026-04-05 lists every estimate you may view, newest first, in the same shape. Many estimates may exist for one tag set; accepted marks the plan.
Accept
POST /api/v1/estimates/est_4k2q9w/accept201 with id, the accept event's id (acc_…), and estimate, the estimate as above with accepted: true. Accepting another estimate for the same tag set later supersedes this one; a report as of an earlier date still shows it. An estimate with no tags cannot be accepted (400). Needs plan on the tag set. See Accept.
Shares
A share is a person's fraction of a project's plan between two dates. Shares over the people of a project may add up to more than 1; the sum is shown, never corrected. A handover is a new share for the new person.
POST /api/v1/shares
{ "person": "mara@kestrel.example", "project": "shop", "fraction": "0.6", "from": "2026-03-01" }to is optional; left out, the share is open-ended. 201:
{ "id": "shr_2b7a…", "person": "mara@kestrel.example", "project": "shop", "fraction": "0.6", "from": "2026-03-01", "to": null, "over": null}over is the sum of the project's shares on the share's first day where it is above 1, such as "1.2". GET /shares?as_of=2026-03-31 lists the shares in force whose project you may view. A person's plan is the sum of their shares times the plans of those projects: Mara's 0.6 of Shop's 232.50 in March is 139.50. It appears in the deviation report grouped by person. See Shares.