Skip to main content
The v2 API gives you your BuildingSwell data: projects and the orders under them, the work tree from phases down to individual steps, your people, and every hour logged against a job. Base URL:
Every request and response is application/json.

​
Quick start

1

Create an API key

In the BuildingSwell app, go to Organization settings → API keys. Admin access is required. The secret is shown once, so store it before you close the dialog.
2

Make your first request

Send the key in an X-API-Key header:
You get back { "values": [...], "hasMore": false }.
3

Learn the shared pattern

Resources share one CRUD and query shape, so standard endpoints and querying cover most of what you need. After that, go straight to the resource you care about.

​
Where to start

Standard endpoints

The CRUD and query pattern every resource shares, and the four things that catch people out.

Querying

Pagination, sorting, filters, search, and joins that resolve names in one request.

Archiving and deleting

What archive does, what delete removes, and why you almost always want archive.

Timesheets

Every hour logged, in one shape. Break carve-out and hour attribution included.

Deliverables

The work tree, its nine node types, and the schedule and progress actions.

Domain concepts

Deliverable writes with the nesting rules enforced. Prefer these over raw writes.

​
Archiving is not deleting

Worth knowing before your first write. DELETE is permanent and cascades, while setting isArchived is reversible and is what the app itself does. See archiving and deleting.