canonical: https://jentic.com/apis/benetics.io/benetics

# Benetics API

Jentic publishes the only available OpenAPI specification for Benetics API, keeping it validated and agent-ready. The Benetics API exposes a cloud construction efficiency platform: projects, plan drawings with versioned revisions, tasks, daily reports and submissions, members, file uploads, exports, and webhooks. Site teams and back-office tools use it to push plans, capture site reports, manage punch-list tasks, and stream activity to downstream systems via webhook subscriptions. The spec covers 46 endpoints across nine resources scoped to a single workspace.

## For AI agents

Manage construction projects, plan revisions, site tasks, and daily reports on Benetics. Subscribe to webhooks to react to project activity in real time.

## Scope

Does not handle accounting, payroll, or material procurement - use for construction project plans, site tasks, daily reports, and webhook events only.

## Capabilities

- Create and update construction projects and their members
- Upload plan drawings and manage versioned plan revisions
- Track punch-list and site tasks scoped to a project
- Retrieve daily report submissions captured by site teams
- Trigger and download project export bundles
- Subscribe webhooks to react to project, task, and document events

## Use cases

### Plan Revision Distribution

Push the latest design drawings into Benetics so site supervisors always work from current plans. The plans and plan-versions endpoints store revisions against a project, and file uploads handle the underlying drawing artefacts. A small integration with a CAD or document management system can be wired up in around a day using POST `/projects/{project_id}/plans` and POST `/projects/{project_id}/plans/{plan_id}/versions.`

Example prompt: Upload a new plan PDF via POST /file-uploads, then POST `/projects/{project_id}/plans/{plan_id}/versions` referencing the uploaded file id

### Daily Site Report Aggregation

Pull daily report submissions from active projects into a head-office dashboard or BI pipeline. The reports and submissions endpoints expose structured site data that can be aggregated by project or member. Building a nightly extract over GET `/projects/{project_id}/reports` and the submissions sub-resource is typically half a day of work.

Example prompt: Iterate every active project, GET `/projects/{project_id}/reports`, and for each report fetch /submissions to collect yesterday's site entries

### Webhook-Driven Task Automation

Use webhook subscriptions to notify a project management or messaging tool whenever a task is created, completed, or reassigned. POST /webhooks registers a callback URL and event filter, and the webhook resource lifecycle is fully managed via the API. End-to-end setup including signature verification typically takes under a day.

Example prompt: POST /webhooks subscribing to task.updated events for a target project, then handle incoming events by posting a summary to a Slack channel

### AI Agent for Site Operations

An AI agent uses Jentic to discover Benetics operations and automate routine site administration: opening tasks from RFI emails, posting plan revisions, or pulling end-of-day reports for a stand-up summary. The agent searches by intent, loads the operation schema from Jentic, and executes against Benetics without browsing the 46-endpoint reference. Through Jentic, integration takes under an hour.

Example prompt: Search Jentic for 'create project task on benetics' and execute the returned operation to open a task with title, description, and assignee

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/projects` | Create a new construction project |
| GET | `/projects/{project_id}/tasks` | List tasks on a project |
| POST | `/projects/{project_id}/plans/{plan_id}/versions` | Add a new plan revision |
| GET | `/projects/{project_id}/reports/{report_id}/submissions` | List submissions for a daily report |
| POST | `/file-uploads` | Upload a file artefact |
| POST | `/webhooks` | Register a webhook subscription |
| GET | `/projects/{project_id}/exports` | List export bundles for a project |

## Key resources

- **Projects** — Create, retrieve, update, and delete construction projects and manage project members
- **Plans** — Manage plan drawings and their versioned revisions per project
- **Tasks** — Open, update, and close punch-list and site tasks scoped to a project
- **Reports** — Read daily reports and their submissions captured on site
- **Documents** — Attach and manage project documents
- **File Uploads** — Upload binary artefacts such as drawings, photos, and report attachments
- **Webhooks** — Subscribe to project, task, document, and report events
- **Exports** — Trigger and retrieve project export bundles

## Why Jentic

- **Setup:** Wiring the Benetics API by hand means carrying a bearer token, learning the project, task, plan, and report endpoints, and threading project ids through every call yourself. Through Jentic you install once, import the Benetics API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Benetics puts the project id in the URL path (`/projects/{project_id}/tasks` and `/projects/{project_id}/reports`), so a rule can pin your agent to one project: it reads that project's tasks and reports and nothing else. You choose the operations it may call, so project creation, plan versions, or webhook creation are not included unless you add them.
- **Credential handling:** Your Benetics bearer token is stored once, encrypted, by your own Jentic One instance and injected as the Authorization header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list project tasks' or 'upload a plan revision', and Jentic returns the matching Benetics operation with its parameter schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Asana API** — General-purpose project and task management alongside Benetics' construction-specific workflows
- **Monday.com API** — Configurable work management platform that can model construction tasks but lacks plan revisioning
- **Trello API** — Lightweight kanban for task tracking without construction-specific resources

## FAQ

### Why is there no official OpenAPI spec for Benetics API?

Benetics does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Benetics 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 Benetics API use?

The Benetics API uses HTTP Bearer authentication - clients send Authorization: Bearer <token> on every request. When called via Jentic, the token is stored encrypted in your Jentic One instance and injected at execution time so the bearer secret never enters the agent context.

### Can I manage plan revisions through the Benetics API?

Yes. POST `/projects/{project_id}/plans` creates a plan, and POST `/projects/{project_id}/plans/{plan_id}/versions` adds a new revision referencing a previously uploaded file id from POST /file-uploads. GET on the same paths lists existing plans and versions.

### How do I subscribe to project events through Jentic?

Run pip install jentic and search for 'subscribe to benetics webhook'. Jentic returns the POST /webhooks operation, the agent loads the schema, and executes with the callback URL and event filter. Webhook subscriptions are then managed via GET, PATCH, and DELETE on `/webhooks/{webhook_id}.`

### What rate limits apply to the Benetics API?

The OpenAPI specification does not document explicit rate limits. Treat 429 responses as a signal to back off and consult the live developer site at https://developer.benetics.io for current quotas before running bulk syncs.

### Can I export a finished project via the API?

Yes. GET `/projects/{project_id}/exports` lists export bundles for a project, and GET `/projects/{project_id}/exports/{export_id}` returns a specific export so an integration can hand off the bundle to a long-term archive or document management system.

### Can I limit what my agent is allowed to do with the Benetics API?

Yes. Because you run Jentic One yourself, your own rules decide which Benetics operations and credentials the agent may use. Benetics puts the project id in the URL path, as in GET `/projects/{project_id}/tasks` and GET `/projects/{project_id}/reports`, so a rule can pin the agent to a single project and let it read only that project's tasks and reports. You choose the operations it may call, so higher-impact actions like POST /projects, plan version uploads, or POST /webhooks stay unavailable unless you add them.