Skip to content

Chore/token usage #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
samwilliamsxc wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Chore/token usage #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b219d1d
feat(v3): rename token cost → average token cost (placeholder TBD)
samwilliamsxc Jul 24, 2026
fe50148
Merge origin/main (whoami) + fill in average token cost values
samwilliamsxc Jul 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions scripts/generate-md-tables.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,7 @@ function collectOps(tagName) {
* "reference/jobs.md#anchor" (cross-page, used in the README index).
*/
function summaryRow(p, method, op, hrefBase = '') {
const cost = op['x-token-cost'];
const cost = op['x-average-token-cost'];
const restricted = op['x-restricted'] ? ' 🔒' : '';
const href = `${hrefBase}#${anchor(op.summary)}`;
return `| \`${method.toUpperCase()}\` | [\`${p}\`](${href})${restricted} | ${esc(cost)} | ${esc(op.summary)} |`;
Expand All @@ -135,7 +135,7 @@ function buildTagMarkdown(tagName) {
const lines = [];

// Summary table
lines.push('| Method | Endpoint | Token cost | Description |');
lines.push('| Method | Endpoint | Average token cost | Description |');
lines.push('| --- | --- | --- | --- |');
for (const { p, method, op } of ops) {
lines.push(summaryRow(p, method, op));
Expand All @@ -156,7 +156,7 @@ function buildTagMarkdown(tagName) {
lines.push(`${method.toUpperCase()} ${BASE_URL}${p}`);
lines.push('```');
lines.push('');
lines.push(`**Token cost:** ${esc(op['x-token-cost'])}`);
lines.push(`**Average token cost:** ${esc(op['x-average-token-cost'])}`);
lines.push('');
if (op.description) {
lines.push(esc(op.description));
Expand Down Expand Up @@ -225,7 +225,7 @@ function buildEndpointIndex() {
if (ops.length === 0) continue;
lines.push(`### [${tagName}](reference/${slug}.md)`);
lines.push('');
lines.push('| Method | Endpoint | Token cost | Description |');
lines.push('| Method | Endpoint | Average token cost | Description |');
lines.push('| --- | --- | --- | --- |');
for (const { p, method, op } of ops) {
lines.push(summaryRow(p, method, op, `reference/${slug}.md`));
Expand Down
2 changes: 1 addition & 1 deletion v3/ApiExamples/Nodejs/node-getModel.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ const API_KEY = '<<YOUR_API_KEY>>';
// Path placeholder — replace with the model key you want to fetch. Must not contain '/'.
const MODEL_KEY = 'your-model-key';

// Comma-separated list of sub-paths to return (maximum 10), 1000 tokens per path.
// Comma-separated list of sub-paths to return (maximum 10). Cost scales with the data returned per path.
// Use `paths` — this is the supported way to read model data. A full model fetch
// (empty string here / omit `paths`) requires extended API access and returns a
// 403 `extended_access_required` in production, where extended access is off.
Expand Down
2 changes: 1 addition & 1 deletion v3/ApiExamples/Nodejs/node-listModels.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ const axios = require('axios');
const URL_PATH = 'https://katapultpro.com/api/v3';
const API_KEY = '<<YOUR_API_KEY>>';

// Token cost: 100 tokens per request.
// Token cost scales with the data returned; see the average in the API reference.
async function run() {
try {
const response = await axios({
Expand Down
2 changes: 1 addition & 1 deletion v3/ApiExamples/Python/py-getModel.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
# Path placeholder — replace with the model key you want to fetch. Must not contain '/'.
MODEL_KEY = 'your-model-key'

# Comma-separated list of sub-paths to return (maximum 10), 1000 tokens per path.
# Comma-separated list of sub-paths to return (maximum 10). Cost scales with the data returned per path.
# Use `paths` — this is the supported way to read model data. A full model fetch
# (None here / omit `paths`) requires extended API access and returns a
# 403 `extended_access_required` in production, where extended access is off.
Expand Down
2 changes: 1 addition & 1 deletion v3/ApiExamples/Python/py-listModels.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
URL_PATH = 'https://katapultpro.com/api/v3'
API_KEY = '<<YOUR_API_KEY>>'

# Token cost: 100 tokens per request.
# Token cost scales with the data returned; see the average in the API reference.
try:
resp = requests.get(f'{URL_PATH}/models', params={'api_key': API_KEY})
print('Status:', resp.status_code)
Expand Down
112 changes: 56 additions & 56 deletions v3/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ traces), plus models and users.
generated from it — see [Maintaining these docs](#maintaining-these-docs).

> **For AI agents:** [`openapi.yaml`](openapi.yaml) is the single source of
> truth for every endpoint, parameter, schema, and token cost (encoded as the
> `x-token-cost` extension on each operation). Prefer it for structured lookups;
> truth for every endpoint, parameter, schema, and average token cost (encoded
> as the `x-average-token-cost` extension on each operation). Prefer it for structured lookups;
> use the Markdown pages for prose, concepts, and examples.

## Quick start
Expand Down Expand Up @@ -49,108 +49,108 @@ in [Quick start](#quick-start) above.

### [Jobs](reference/jobs.md)

| Method | Endpoint | Token cost | Description |
| Method | Endpoint | Average token cost | Description |
| --- | --- | --- | --- |
| `GET` | [`/jobs`](reference/jobs.md#list-all-jobs) | 1 | List all jobs |
| `POST` | [`/jobs`](reference/jobs.md#create-a-job) | 10 | Create a job |
| `GET` | [`/jobs/{job_id}`](reference/jobs.md#get-a-job-partial-data) | 1 | Get a job (partial data) |
| `POST` | [`/jobs/{job_id}`](reference/jobs.md#update-a-job) | 10 | Update a job |
| `POST` | [`/jobs/{job_id}/raw`](reference/jobs.md#raw-job-write) 🔒 | 10 | Raw job write |
| `GET` | [`/jobs`](reference/jobs.md#list-all-jobs) | 2014 | List all jobs |
| `POST` | [`/jobs`](reference/jobs.md#create-a-job) | 17 | Create a job |
| `GET` | [`/jobs/{job_id}`](reference/jobs.md#get-a-job-partial-data) | 3 | Get a job (partial data) |
| `POST` | [`/jobs/{job_id}`](reference/jobs.md#update-a-job) | 49 | Update a job |
| `POST` | [`/jobs/{job_id}/raw`](reference/jobs.md#raw-job-write) 🔒 | 1 | Raw job write |
| `GET` | [`/jobs/{job_id}/status`](reference/jobs.md#get-job-status) | 1 | Get job status |
| `POST` | [`/jobs/{job_id}/status`](reference/jobs.md#update-job-status) | 10 | Update job status |
| `POST` | [`/jobs/{job_id}/status`](reference/jobs.md#update-job-status) | 1 | Update job status |

### [Nodes](reference/nodes.md)

| Method | Endpoint | Token cost | Description |
| Method | Endpoint | Average token cost | Description |
| --- | --- | --- | --- |
| `GET` | [`/jobs/{job_id}/nodes`](reference/nodes.md#get-all-nodes) | 1 | Get all nodes |
| `POST` | [`/jobs/{job_id}/nodes`](reference/nodes.md#create-a-node) | 10 | Create a node |
| `GET` | [`/jobs/{job_id}/nodes`](reference/nodes.md#get-all-nodes) | 138 | Get all nodes |
| `POST` | [`/jobs/{job_id}/nodes`](reference/nodes.md#create-a-node) | 15 | Create a node |
| `GET` | [`/jobs/{job_id}/nodes/{node_id}`](reference/nodes.md#get-a-node) | 1 | Get a node |
| `POST` | [`/jobs/{job_id}/nodes/{node_id}`](reference/nodes.md#update-a-node) | 10 | Update a node |
| `DELETE` | [`/jobs/{job_id}/nodes/{node_id}`](reference/nodes.md#delete-a-node) | 10 | Delete a node |
| `POST` | [`/jobs/{job_id}/nodes/{node_id}/photos`](reference/nodes.md#upload-a-photo-to-a-node) | 10 | Upload a photo to a node |
| `POST` | [`/jobs/{job_id}/nodes/{node_id}`](reference/nodes.md#update-a-node) | 40 | Update a node |
| `DELETE` | [`/jobs/{job_id}/nodes/{node_id}`](reference/nodes.md#delete-a-node) | 4933 | Delete a node |
| `POST` | [`/jobs/{job_id}/nodes/{node_id}/photos`](reference/nodes.md#upload-a-photo-to-a-node) | 5 | Upload a photo to a node |

### [Connections](reference/connections.md)

| Method | Endpoint | Token cost | Description |
| Method | Endpoint | Average token cost | Description |
| --- | --- | --- | --- |
| `GET` | [`/jobs/{job_id}/connections`](reference/connections.md#get-all-connections) | 1 | Get all connections |
| `POST` | [`/jobs/{job_id}/connections`](reference/connections.md#create-a-connection) | 10 | Create a connection |
| `GET` | [`/jobs/{job_id}/connections`](reference/connections.md#get-all-connections) | 127 | Get all connections |
| `POST` | [`/jobs/{job_id}/connections`](reference/connections.md#create-a-connection) | 17 | Create a connection |
| `GET` | [`/jobs/{job_id}/connections/{connection_id}`](reference/connections.md#get-a-connection) | 1 | Get a connection |
| `POST` | [`/jobs/{job_id}/connections/{connection_id}`](reference/connections.md#update-a-connection) | 10 | Update a connection |
| `DELETE` | [`/jobs/{job_id}/connections/{connection_id}`](reference/connections.md#delete-a-connection) | 10 | Delete a connection |
| `POST` | [`/jobs/{job_id}/connections/{connection_id}`](reference/connections.md#update-a-connection) | 18 | Update a connection |
| `DELETE` | [`/jobs/{job_id}/connections/{connection_id}`](reference/connections.md#delete-a-connection) | 2566 | Delete a connection |

### [Sections](reference/sections.md)

| Method | Endpoint | Token cost | Description |
| Method | Endpoint | Average token cost | Description |
| --- | --- | --- | --- |
| `GET` | [`/jobs/{job_id}/connections/{connection_id}/sections`](reference/sections.md#get-all-sections-on-a-connection) | 1 | Get all sections on a connection |
| `POST` | [`/jobs/{job_id}/connections/{connection_id}/sections`](reference/sections.md#create-a-section) | 10 | Create a section |
| `POST` | [`/jobs/{job_id}/connections/{connection_id}/sections`](reference/sections.md#create-a-section) | 17 | Create a section |
| `GET` | [`/jobs/{job_id}/connections/{connection_id}/sections/{section_id}`](reference/sections.md#get-a-section) | 1 | Get a section |
| `POST` | [`/jobs/{job_id}/connections/{connection_id}/sections/{section_id}`](reference/sections.md#update-a-section) | 10 | Update a section |
| `DELETE` | [`/jobs/{job_id}/connections/{connection_id}/sections/{section_id}`](reference/sections.md#delete-a-section) | 10 | Delete a section |
| `POST` | [`/jobs/{job_id}/connections/{connection_id}/sections/{section_id}/photos`](reference/sections.md#upload-a-photo-to-a-section) | 10 | Upload a photo to a section |
| `POST` | [`/jobs/{job_id}/connections/{connection_id}/sections/{section_id}`](reference/sections.md#update-a-section) | 16 | Update a section |
| `DELETE` | [`/jobs/{job_id}/connections/{connection_id}/sections/{section_id}`](reference/sections.md#delete-a-section) | 5920 | Delete a section |
| `POST` | [`/jobs/{job_id}/connections/{connection_id}/sections/{section_id}/photos`](reference/sections.md#upload-a-photo-to-a-section) | 3 | Upload a photo to a section |

### [Photos](reference/photos.md)

| Method | Endpoint | Token cost | Description |
| Method | Endpoint | Average token cost | Description |
| --- | --- | --- | --- |
| `GET` | [`/jobs/{job_id}/photos`](reference/photos.md#get-all-photos) | 1 | Get all photos |
| `POST` | [`/jobs/{job_id}/photos`](reference/photos.md#upload-a-photo) | 10 | Upload a photo |
| `GET` | [`/jobs/{job_id}/photos/{photo_id}`](reference/photos.md#get-a-photo) | 1 | Get a photo |
| `GET` | [`/jobs/{job_id}/photos/{photo_id}/url`](reference/photos.md#get-a-photo-download-url) | 1 | Get a photo download URL |
| `POST` | [`/jobs/{job_id}/photos/{photo_id}/associate`](reference/photos.md#associate-a-photo-to-an-item) | 10 | Associate a photo to an item |
| `GET` | [`/jobs/{job_id}/photos`](reference/photos.md#get-all-photos) | 1147 | Get all photos |
| `POST` | [`/jobs/{job_id}/photos`](reference/photos.md#upload-a-photo) | 1 | Upload a photo |
| `GET` | [`/jobs/{job_id}/photos/{photo_id}`](reference/photos.md#get-a-photo) | 2 | Get a photo |
| `GET` | [`/jobs/{job_id}/photos/{photo_id}/url`](reference/photos.md#get-a-photo-download-url) | 4 | Get a photo download URL |
| `POST` | [`/jobs/{job_id}/photos/{photo_id}/associate`](reference/photos.md#associate-a-photo-to-an-item) | 1286 | Associate a photo to an item |

### [Photo Elements](reference/photo-elements.md)

| Method | Endpoint | Token cost | Description |
| Method | Endpoint | Average token cost | Description |
| --- | --- | --- | --- |
| `GET` | [`/jobs/{job_id}/photos/{photo_id}/photo_elements`](reference/photo-elements.md#get-all-elements-on-a-photo) | 1 | Get all elements on a photo |
| `POST` | [`/jobs/{job_id}/photos/{photo_id}/photo_elements`](reference/photo-elements.md#create-a-photo-element) | 10 | Create a photo element |
| `GET` | [`/jobs/{job_id}/photos/{photo_id}/photo_elements/{element_id}`](reference/photo-elements.md#get-a-photo-element) | 1 | Get a photo element |
| `POST` | [`/jobs/{job_id}/photos/{photo_id}/photo_elements/{element_id}`](reference/photo-elements.md#update-a-photo-element) | 10 | Update a photo element |
| `DELETE` | [`/jobs/{job_id}/photos/{photo_id}/photo_elements/{element_id}`](reference/photo-elements.md#delete-a-photo-element) | 10 | Delete a photo element |
| `GET` | [`/jobs/{job_id}/photos/{photo_id}/photo_elements`](reference/photo-elements.md#get-all-elements-on-a-photo) | 4 | Get all elements on a photo |
| `POST` | [`/jobs/{job_id}/photos/{photo_id}/photo_elements`](reference/photo-elements.md#create-a-photo-element) | 515 | Create a photo element |
| `GET` | [`/jobs/{job_id}/photos/{photo_id}/photo_elements/{element_id}`](reference/photo-elements.md#get-a-photo-element) | 7 | Get a photo element |
| `POST` | [`/jobs/{job_id}/photos/{photo_id}/photo_elements/{element_id}`](reference/photo-elements.md#update-a-photo-element) | 994 | Update a photo element |
| `DELETE` | [`/jobs/{job_id}/photos/{photo_id}/photo_elements/{element_id}`](reference/photo-elements.md#delete-a-photo-element) | 933 | Delete a photo element |

### [Calibration Anchors](reference/calibration-anchors.md)

| Method | Endpoint | Token cost | Description |
| Method | Endpoint | Average token cost | Description |
| --- | --- | --- | --- |
| `GET` | [`/jobs/{job_id}/photos/{photo_id}/calibration_anchors`](reference/calibration-anchors.md#get-all-calibration-anchors-on-a-photo) | 1 | Get all calibration anchors on a photo |
| `POST` | [`/jobs/{job_id}/photos/{photo_id}/calibration_anchors`](reference/calibration-anchors.md#create-a-calibration-anchor) | 10 | Create a calibration anchor |
| `GET` | [`/jobs/{job_id}/photos/{photo_id}/calibration_anchors`](reference/calibration-anchors.md#get-all-calibration-anchors-on-a-photo) | 4 | Get all calibration anchors on a photo |
| `POST` | [`/jobs/{job_id}/photos/{photo_id}/calibration_anchors`](reference/calibration-anchors.md#create-a-calibration-anchor) | 435 | Create a calibration anchor |
| `GET` | [`/jobs/{job_id}/photos/{photo_id}/calibration_anchors/{anchor_id}`](reference/calibration-anchors.md#get-a-calibration-anchor) | 1 | Get a calibration anchor |
| `POST` | [`/jobs/{job_id}/photos/{photo_id}/calibration_anchors/{anchor_id}`](reference/calibration-anchors.md#update-a-calibration-anchor) | 10 | Update a calibration anchor |
| `DELETE` | [`/jobs/{job_id}/photos/{photo_id}/calibration_anchors/{anchor_id}`](reference/calibration-anchors.md#delete-a-calibration-anchor) | 10 | Delete a calibration anchor |
| `POST` | [`/jobs/{job_id}/photos/{photo_id}/calibration_anchors/{anchor_id}`](reference/calibration-anchors.md#update-a-calibration-anchor) | 2691 | Update a calibration anchor |
| `DELETE` | [`/jobs/{job_id}/photos/{photo_id}/calibration_anchors/{anchor_id}`](reference/calibration-anchors.md#delete-a-calibration-anchor) | 685 | Delete a calibration anchor |

### [Traces](reference/traces.md)

| Method | Endpoint | Token cost | Description |
| Method | Endpoint | Average token cost | Description |
| --- | --- | --- | --- |
| `GET` | [`/jobs/{job_id}/traces`](reference/traces.md#get-all-traces) | 1 | Get all traces |
| `POST` | [`/jobs/{job_id}/traces`](reference/traces.md#create-a-trace) | 10 | Create a trace |
| `GET` | [`/jobs/{job_id}/traces/{trace_id}`](reference/traces.md#get-a-trace) | 1 | Get a trace |
| `POST` | [`/jobs/{job_id}/traces/{trace_id}`](reference/traces.md#update-a-trace) | 10 | Update a trace |
| `DELETE` | [`/jobs/{job_id}/traces/{trace_id}`](reference/traces.md#delete-a-trace) | 10 | Delete a trace |
| `GET` | [`/jobs/{job_id}/traces`](reference/traces.md#get-all-traces) | 175 | Get all traces |
| `POST` | [`/jobs/{job_id}/traces`](reference/traces.md#create-a-trace) | 5802 | Create a trace |
| `GET` | [`/jobs/{job_id}/traces/{trace_id}`](reference/traces.md#get-a-trace) | 2 | Get a trace |
| `POST` | [`/jobs/{job_id}/traces/{trace_id}`](reference/traces.md#update-a-trace) | 7272 | Update a trace |
| `DELETE` | [`/jobs/{job_id}/traces/{trace_id}`](reference/traces.md#delete-a-trace) | 5902 | Delete a trace |

### [Models](reference/models.md)

| Method | Endpoint | Token cost | Description |
| Method | Endpoint | Average token cost | Description |
| --- | --- | --- | --- |
| `GET` | [`/models`](reference/models.md#get-model-options) | 100 | Get model options |
| `GET` | [`/models/{modelKey}`](reference/models.md#get-model-data) | 9900 (full) \| 1000 per path (max 10) | Get model data |
| `GET` | [`/models`](reference/models.md#get-model-options) | 2 | Get model options |
| `GET` | [`/models/{modelKey}`](reference/models.md#get-model-data) | 394 | Get model data |

### [Users](reference/users.md)

| Method | Endpoint | Token cost | Description |
| Method | Endpoint | Average token cost | Description |
| --- | --- | --- | --- |
| `GET` | [`/users`](reference/users.md#list-all-users) | 1 | List all users |
| `GET` | [`/users`](reference/users.md#list-all-users) | 186 | List all users |
| `GET` | [`/users/whoami`](reference/users.md#get-current-user) | 1 | Get current user |
| `GET` | [`/users/{user_id}`](reference/users.md#get-a-user) | 1 | Get a user |
| `GET` | [`/users/{user_id}/active_state`](reference/users.md#get-user-active-state) 🔒 | 1 | Get user active state |
| `POST` | [`/users/{user_id}/active_state`](reference/users.md#set-user-active-state) 🔒 | 10 | Set user active state |
| `POST` | [`/users/{user_id}/active_state`](reference/users.md#set-user-active-state) 🔒 | 1 | Set user active state |

### [Companies](reference/companies.md)

| Method | Endpoint | Token cost | Description |
| Method | Endpoint | Average token cost | Description |
| --- | --- | --- | --- |
| `GET` | [`/companies/{company_id}/tracked_actions`](reference/companies.md#list-tracked-actions) | 1 | List tracked actions |
| `GET` | [`/companies/{company_id}/action_models`](reference/companies.md#list-action-models) | 1 | List action models |
Expand All @@ -163,7 +163,7 @@ in [Quick start](#quick-start) above.

## Concepts

- [Rate limits & the token bucket](rate-limits.md) — token costs, refills, and
- [Rate limits & the token bucket](rate-limits.md) — average token costs, refills, and
best practices for heavy scripts.
- [Working with attributes](concepts/attributes.md)
- [Complex & codependent parameters](concepts/complex-parameters.md) — worked examples for tricky field combinations (photo association, the attribute trio, `make_midpoint`, `onlyIfExists`, model `paths`).
Expand Down
15 changes: 8 additions & 7 deletions v3/concepts/complex-parameters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -136,17 +136,18 @@ differently based on `paths`:

- **No `paths`** → returns the **full** model. This **requires extended API
access** (otherwise `403 extended_access_required`) and, because extended
access is off in production, is **unavailable on `katapultpro.com`**. When
permitted, it costs **9,900 tokens** (nearly the entire default bucket).
- **With `paths`** (comma-separated, **max 10**) → returns only those sub-paths
and costs **1,000 tokens per path**. Open to all callers — the supported route
for most integrations.
access is off in production, is **unavailable on `katapultpro.com`**. A full
model is large, so when permitted it is the most expensive way to read model
data.
- **With `paths`** (comma-separated, **max 10**) → returns only those sub-paths,
so it costs far less than a full fetch. Open to all callers — the supported
route for most integrations.

Prefer `paths` whenever you need only part of a model. See
[Rate limits & the token bucket](../rate-limits.md#token-costs).
[Rate limits & the token bucket](../rate-limits.md#average-token-costs).

```sh
# 2 paths -> 2,000 tokens, instead of 9,900 for the whole model:
# Fetch only the sub-paths you need, instead of the whole model:
curl "https://katapultpro.com/api/v3/models/MODEL_KEY?api_key=KEY&paths=attributes,button_groups"
```

Expand Down
Loading