What this does
The Projects API lets you manage project records programmatically. Projects are used to tag invoices, bills, expenses, and mileage so income vs cost per job can be tracked. Each project response includes aggregated income, costs, and profit figures rolled up from the linked records.
When to use it
Use this endpoint when the bot needs to create or look up a project to attach to an invoice line, bill, or expense — e.g. "log £42 to the Smith House Refit job". Trades, services businesses, and anyone tracking jobs/clients separately will want this.
Authentication and scopes
Requests must include Authorization: Bearer rly_your_key_here. Each endpoint requires one of:
projects:read— list and retrieve projectsprojects:write— create, update, and delete projects
Endpoints
List projects
GET /api/v1/projects
Returns a paginated list of projects with their aggregated income/costs/profit. Supports ?page=1&limit=50 query parameters.
Create a project
POST /api/v1/projects
{
"name": "Smith House Refit",
"description": "Phase 1 — kitchen and utility",
"customerId": "cust_abc123",
"budget": 25000,
"currency": "GBP",
"startDate": "2026-04-01",
"endDate": "2026-08-31"
}
name is required. All other fields are optional. budget accepts a number or numeric string.
Response (201 Created): the created project object including id, status: "active", and timestamps.
Get a single project
GET /api/v1/projects/:id
Returns the project with aggregated income, costs, and profit.
Update a project
PATCH /api/v1/projects/:id
{
"name": "Smith House Refit (revised)",
"status": "completed",
"budget": 28000
}
All fields are optional and only the supplied keys are updated. Allowed values for status: active, completed, archived.
Delete a project
DELETE /api/v1/projects/:id
Deletes the project. Any invoices or bills tagged with this project have their project_id set to NULL first — the underlying records are not deleted.
Response: { "data": { "id": "...", "deleted": true } }
404 not_found— project does not exist
Test mode
Keys flagged as test mode validate request bodies but skip database writes. The response includes "test": true so you can exercise the integration safely.