canonical: https://jentic.com/apis/builtfirst.com/builtfirst # Builtfirst API Jentic publishes the only available OpenAPI specification for Builtfirst API, keeping it validated and agent-ready. Builtfirst is a construction project management and building operations platform. The API exposes the core record types - projects, buildings, units, tasks, inspections, and documents - so general contractors and operators can plug Builtfirst into scheduling tools, BIM systems, and document repositories. Use it to script project setup, sync inspection results into compliance tooling, push task updates from the field, and centralise plan documents in a single location. ## For AI agents Manage Builtfirst construction projects, buildings, units, tasks, inspections, and documents across 21 REST endpoints. ## Scope Does not handle accounting, payroll, or BIM model authoring - use for project, building, unit, task, inspection, and document records only. ## Capabilities - Create and update construction projects with their associated buildings - Register buildings under a project and break them into individual units - Create, list, and update tasks tied to a project, building, or unit - Record building inspections and read past inspection results - Upload, retrieve, and delete project documents such as plans and certificates - Look up a specific project, building, unit, task, or inspection by ID - Pull the full task list to drive schedule and compliance dashboards ## Use cases ### Project Kickoff Provisioning When a new construction project starts, provision the Builtfirst record set in one workflow. The agent posts to /projects to create the project, then iterates building and unit records via /buildings and /units, attaching plan documents through /documents. This replaces a checklist of manual entries on the dashboard with a repeatable script. Example prompt: Create a Builtfirst project named Riverside Tower, add three buildings, and upload the site plan PDF as a project document. ### Field Task Updates Foremen mark tasks complete from a tablet on site. The agent translates each update into a PUT `/tasks/{id}` call with the new status and any notes captured in the field. GET /tasks lets a daily report pull every task that closed in the last 24 hours so a project manager can confirm progress without logging in. Example prompt: Mark task 4421 complete with the note Roofing tar applied at 2pm and post a daily summary of completed tasks to the project Slack channel. ### Compliance Inspection Logging Inspectors record results in their own app and push them into Builtfirst for compliance archival. POST /inspections accepts the inspection payload with date, inspector, result, and unit reference. Combined with /documents you can attach inspection certificates so future audits can be answered with a single GET call. Example prompt: Record an inspection for unit 8821 with result passed, inspector ID 12, and attach the inspection certificate PDF to the project. ### AI Agent Construction Assistant via Jentic An agent connected via Jentic can answer questions like which units are still open on this project or which tasks slipped past their due date. The agent searches Jentic for list tasks, loads the GET /tasks schema, and executes against the operator's vault-stored Builtfirst API key without ever exposing it. Example prompt: Search Jentic for list construction tasks, load the schema, and return tasks past their due date for project_id 314. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/projects` | Create a project | | POST | `/buildings` | Create a building | | POST | `/units` | Create a unit | | POST | `/tasks` | Create a task | | PUT | `/tasks/{id}` | Update a task | | POST | `/inspections` | Create an inspection record | | POST | `/documents` | Upload a document | ## Key resources - **Projects** — Create, list, and update construction projects - **Buildings** — Manage buildings inside a project - **Units** — Manage individual units within a building - **Tasks** — Create, list, and update field and punch list tasks - **Inspections** — Record and read inspection results - **Documents** — Upload, retrieve, and delete project documents ## Why Jentic - **Setup:** Wiring Builtfirst by hand means learning its X-API-Key header auth against api.builtfirst.com and shaping each project, building, and inspection payload yourself. Through Jentic you install once, import Builtfirst from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** Builtfirst creates projects, buildings, units, and inspections from the request body and identifies a task by id only when updating it, so scope the agent by the operations it needs, such as creating a project or recording an inspection. Because you choose the allowed operations, it can create records without being able to update existing tasks unless you add that. - **Credential handling:** Your Builtfirst X-API-Key is stored once, encrypted, by your own Jentic One instance and injected as the header at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'create a project' or 'record an inspection', and Jentic returns the matching Builtfirst operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Buildium API** — Buildium manages residential property operations after a building is occupied; Builtfirst manages the construction phase before that. - **Buildkite API** — Unrelated software CI tool listed as a name-match neighbour, not a substantive integration. - **BulkSMS API** — BulkSMS sends SMS notifications to subcontractors when Builtfirst tasks are assigned or fall overdue. ## FAQ ### Why is there no official OpenAPI spec for Builtfirst API? Builtfirst does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Builtfirst API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Builtfirst API use? Builtfirst uses an API key passed in the X-API-Key header on every request. Through Jentic, the key is stored encrypted in the vault and the header is constructed at execution time, so the agent never sees the raw value. ### Can I record an inspection result through the Builtfirst API? Yes. POST /inspections accepts a payload with inspection date, inspector, result, and the unit it relates to. GET /inspections and GET `/inspections/{id}` let you list past results and pull the detail for a specific record. ### Can I attach documents like site plans to a Builtfirst project? Yes. POST /documents uploads a file tied to a project, GET `/documents/{id}` fetches it back, and DELETE `/documents/{id}` removes it. Use it to centralise plans, certificates, and inspection paperwork. ### What are the rate limits for the Builtfirst API? Builtfirst does not document explicit rate limits in the OpenAPI spec. Treat the API as fair-use per account and add retry-with-backoff for HTTP 429 responses, especially on bulk task or document operations. ### How do I list Builtfirst tasks from an AI agent through Jentic? Run pip install jentic and authenticate with your ak_* key. Search Jentic with list construction tasks, load the GET /tasks operation, and execute it with your filter parameters. Jentic injects the X-API-Key header from your stored credential. ### Can I limit what my agent is allowed to do with the Builtfirst API? Yes. Because Jentic One is self-hosted by you, your own rules decide which Builtfirst operations and credentials the agent may use. You can allow it to create records through POST /projects, POST /buildings, POST /units, and POST /inspections while withholding the ability to update an existing task via PUT `/tasks/{id}.` The agent can only call the operations you grant, so it never touches endpoints outside that scope.