Getting started

The FOREMAN public API lets you work with your tenant's data — your company's isolated FOREMAN workspace — outside the web app: wiring up integrations, exporting to other systems, or (the headline use case) connecting FOREMAN to an AI assistant to ask plain-language questions over your site data.

Everything runs over one tenant-scoped HTTP surface. The same operations are also exposed as MCP tools so an assistant like Claude or ChatGPT can call them directly.

What you can do in v1

Write:

• Create, read, update, and delete Projects, Tasks, and Form templates — building form templates over the API (or via an AI assistant) is expected to be the primary way templates get made.
• Manage crew — assign and unassign users to projects, and set a site manager.
• Manage users — create, update, revoke, reinstate, and reset passwords.
• Log diary entries on behalf of a crew member, and upload documents and diary photos (register the file, then upload it to the secure link we return).
• Edit induction content for a project.
• Generate document download links and an upgrade Checkout link.

Read (for aggregation): projects, tasks, users, diary entries, form submissions, the induction register, and document metadata — the records an assistant reads to answer questions like "how many hours did Jamie log on Hawthorn this fortnight?".

Filling in and submitting forms, and the public visitor-induction flow, stay in the app for now.

Base URL and versioning

All endpoints live under /api/v1 on your FOREMAN deployment. /v1 is fixed for this version; any breaking change ships under a new version prefix.

Sign up

You don't need the dashboard to start. A single unauthenticated call creates an active tenant and returns a working API key immediately — no browser, no waiting on a verification email:

curl -X POST https://app.foremanapp.com.au/api/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"me@example.com","businessName":"Acme Builders"}'
# { "apiKey": "…use it now", "tenantId": "…", "message": "…" }

A code-capable AI assistant can do this for you and wire the key straight into its tools — see Connect an AI assistant. We email a link to set a dashboard password and confirm your email, but it gates nothing.

If the email is already registered, you get the same message with an empty apiKey — we don't reveal whether an account exists, so grab your key from the dashboard instead. Signup is also rate-limited per IP (429 if you retry too often).

Next steps

1. Authentication — get your tenant API key and send your first request.
2. Connect an AI assistant (MCP) — connect Claude, ChatGPT, or another MCP client to your tenant.
3. API reference — every endpoint, request, and response, generated from the OpenAPI contract.