API reference

A small, honest REST API

Suppliers read their catalogue and orders; platforms read a builder’s projects, schedule and materials. JSON in, JSON out, standard bearer auth. Everything documented below is live unless it’s tagged beta or planned.

Base URL

https://www.buildpaperless.com.au/api/v1

Authentication

Send your key as a bearer token. Keys start with bp_ and are created in the developer settings of a builder’s account.

Authorization: Bearer bp_live_xxx

Rate limits & errors

Every response carries the current limit state:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1750000000

Errors use a stable machine-readable code:

{ "error": {
    "code": "forbidden_scope",
    "message": "This key is missing the required scope: materials:read."
} }

Quick start

Your first call

# Verify your key
curl https://www.buildpaperless.com.au/api/v1/me \
  -H "Authorization: Bearer bp_live_xxx"

# The materials list for a project
curl https://www.buildpaperless.com.au/api/v1/projects/proj_123/materials \
  -H "Authorization: Bearer bp_live_xxx"

Endpoints

Everything you can call

GET/v1/me

Verify a key and read its scopes and rate limit

any valid keyAvailable

GET/v1/products

Your product catalogue: SKUs, pricing, stock, lead times

catalogue:readAvailable

GET/v1/products/{id}

A single catalogue item

catalogue:readAvailable

POST/v1/products

Publish a new catalogue item

catalogue:writeAvailable

PATCH/v1/products/{id}

Update pricing, stock, lead time or availability

catalogue:writeAvailable

DELETE/v1/products/{id}

Withdraw an item (deactivates, never deletes history)

catalogue:writeAvailable

GET/v1/orders

Orders builders have placed with you, with line items

orders:readAvailable

GET/v1/orders/{id}

A single order with its line items

orders:readAvailable

PATCH/v1/orders/{id}

Write fulfilment status and delivery dates back

orders:writeAvailable

GET/v1/projects

List the organisation’s projects

projects:readAvailable

GET/v1/projects/{id}/schedule

The milestone schedule for a project

schedule:readAvailable

GET/v1/projects/{id}/materials

The materials list for a project

materials:readAvailable

POST/v1/projects/{id}/materials

Add a line to the project’s materials list

materials:writeAvailable

PATCH/v1/materials/{id}

Update a materials line (supplier fields need suppliers:write)

materials:writeAvailable

POST/v1/webhooks

webhooksPlanned

GET/v1/rfqs

Quote requests addressed to you

rfqs:readPlanned

On the roadmap

Catalogue publish (POST /v1/products) is in beta. Signed webhook delivery for order.placed, schedule.updated and materials.updated is rolling out. Quote-request read (rfqs:read) and delivery write-back (orders:write) follow, gated behind approval.

See pricing