canonical: https://jentic.com/apis/cupixworks.com/cupixworks # CupixWorks API Jentic publishes the only available OpenAPI specification for CupixWorks API, keeping it validated and agent-ready. The CupixWorks API exposes the construction and built-environment digital-twin platform, which lets teams manage 3D site captures and overlay annotations, categories, statuses, progress milestones, workflows, and review steps. The API covers full CRUD on annotation layers, including publish and unpublish actions and per-layer metadata, and parallel CRUD for categories, progress entries, statuses, workflows, and reviews. Authentication uses a bearer token, suitable for server-side automation that ingests project events and synchronises CupixWorks records. ## For AI agents Manage annotation layers, categories, progress, statuses, workflows, and reviews on CupixWorks construction digital twins. Useful for AI agents that automate site documentation and review handoffs. ## Scope Does not handle 3D capture upload, viewer rendering, or user account management - use for CupixWorks annotation layers, categories, progress, statuses, workflows, and reviews only. ## Capabilities - Create, update, publish, and unpublish annotation layers via /annotation-layers operations - Read and write per-annotation-layer metadata via `/annotation-layers/{id}/metadata` - Manage categories used to classify annotations via /categories CRUD - Track construction progress entries via the /progress endpoints - Manage workflow definitions and statuses for review steps - Drive review records that move work between team members via /reviews ## Use cases ### Automated Construction Progress Logging A construction project agent can record weekly progress entries against milestones in CupixWorks based on data from a project management tool. By calling the /progress endpoints with the relevant site, milestone, and timestamp, the agent keeps the digital twin in sync with reported progress without site engineers manually duplicating updates. Example prompt: Call POST /progress with the milestone ID and percent complete pulled from the project plan. ### Annotation Layer Review Bot A site supervisor's review bot can list pending annotation layers, route them to the right reviewer using the workflow and status endpoints, and publish the layers once approval is logged. The publish and unpublish endpoints make it safe to gate releases of new annotations to the wider team only after sign-off. Example prompt: List annotation layers in pending status, then call PUT `/annotation-layers/{id}/publish` for each one approved by the reviewer. ### Category and Workflow Configuration When a new project starts, a setup agent can stamp the standard categories, statuses, and workflow definitions into the CupixWorks project so the team starts from a consistent template. Calls to /categories, /statuses, and /workflows replace manual click-through configuration with a repeatable script. Example prompt: Loop the standard category list and call POST /categories for each entry, then POST /workflows with the standard review states. ### AI Agent Integration via Jentic An AI assistant for a construction or surveying team can use Jentic to discover CupixWorks operations rather than implementing 31 endpoints directly. The agent searches Jentic for an intent like 'create an annotation layer on a site capture', loads the schema, and runs the call against the bearer token Jentic holds for the project. Example prompt: Use Jentic search for 'create an annotation layer on a CupixWorks site' and execute the matching POST /annotation-layers operation. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/annotation-layers` | List annotation layers | | POST | `/annotation-layers` | Create an annotation layer | | PUT | `/annotation-layers/{id}` | Update an annotation layer | | PUT | `/annotation-layers/{id}/publish` | Publish an annotation layer | | PUT | `/annotation-layers/{id}/unpublish` | Unpublish an annotation layer | | GET | `/annotation-layers/{id}/metadata` | Get annotation layer metadata | | GET | `/categories` | List categories | ## Key resources - **Annotation Layers** — Create, update, publish, and unpublish annotation layers and their metadata. - **Categories** — Manage the categories that tag annotations on a project. - **Progress** — Record and read construction progress entries. - **Statuses** — Define and read status values used in workflows. - **Workflows** — Define multi-step review and approval workflows. - **Reviews** — Drive review records for annotation layers and progress. ## Why Jentic - **Setup:** Wiring the CupixWorks API by hand means placing the bearer token in the Authorization header, targeting the api.cupixworks.com host, and handling retries across annotation and workflow routes yourself. Through Jentic you install once, import the CupixWorks API from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** CupixWorks puts the annotation layer id in the URL path (`/annotation-layers/{id}`), so a rule can pin your agent to one annotation layer: it can read and update that layer and nothing else. You choose the operations it may call, so ones like publishing or unpublishing a layer are not included unless you add them. - **Credential handling:** Your CupixWorks bearer token is stored once, encrypted, by your own Jentic One instance and injected into 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 'create an annotation layer on a CupixWorks site', and Jentic returns the matching CupixWorks operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **GitHub REST API** — GitHub stores construction project automation scripts that drive CupixWorks updates. - **HubSpot CRM API** — HubSpot tracks the customer relationship for the project that CupixWorks documents. - **Wayback Machine API** — Wayback Machine archives public CupixWorks project pages for historical reference. ## FAQ ### Why is there no official OpenAPI spec for CupixWorks API? CupixWorks does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call CupixWorks 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 CupixWorks API use? CupixWorks uses an HTTP bearer token in the Authorization header. Through Jentic the token is stored in your encrypted Jentic One instance and injected at request time so the agent never handles the raw secret in its prompt or outputs. ### Can I publish an annotation layer with the CupixWorks API? Yes. After creating a layer with POST /annotation-layers, run PUT `/annotation-layers/{id}/publish` to publish it to the wider team. Use the matching unpublish endpoint to revert if a reviewer flags an issue. ### What are the rate limits for the CupixWorks API? The Jentic-maintained spec does not publish explicit rate limits because CupixWorks does not document them publicly. Use modest batch sizes when bulk-creating annotation layers or progress entries and back off on 429 responses. ### How do I create an annotation layer with the CupixWorks API through Jentic? Run pip install jentic, search Jentic for 'create an annotation layer on a CupixWorks site', load the schema for POST /annotation-layers, and execute it with the site and metadata. Jentic injects the bearer token from your Jentic One instance so the integration code stays clean. ### How do I track construction progress with the CupixWorks API? Use the /progress endpoints to record progress entries against milestones. Pair them with the workflow and status endpoints to move milestones through the project's review states automatically. ### Can I limit what my agent is allowed to do with the CupixWorks API? Yes. Because you run Jentic One yourself, your own rules decide which CupixWorks operations and credentials the agent may use. Since the API puts the annotation layer id in the path (`/annotation-layers/{id}`), you can pin the agent to a single layer so it only reads and updates that one and nothing else. You also choose the operations it may call, so publishing or unpublishing a layer stays off limits unless you explicitly add it.