API schema

A complete list of all the available APIs can be found in the API Reference including Try Me code snippets.

Alternatively, you can view all the APIs in postman from here. Or you can fork the full Postman collection from here: or the SDK subset collection from here: .

Note that in all the examples provided, the base URL will be generic or undefined. It is important to make sure the base URL is set to your workspace using the format https://<<workspace>>.api.vitruvi.cc.

For example: https://training.api.vitruvi.cc

There is a Python SDK available for a select subset of the API endpoints. This can be found here:

The Python SDK is still in beta and does not contain the complete set APIs, however more are being added every release. Please talk to your Customer Success Manager to request any additional APIs to be prioritized if required.

Choosing the Right API

Reporting APIs

Reporting is a primary use case for Vitruvi APIs. These APIs are categorized into _Query APIs, Export APIs, and Raw APIs. Understanding when to use each type is crucial for efficient data handling and integration.

_Query APIs

Query APIs in this context are any API endpoints that are suffixed with _query. _Query APIs offer pre-joined, normalized results for entities like Design Elements or Work Items. They are ideal for replicating data as seen in Vitruvi's grids, providing aggregated data in a single call. These APIs are generally preferred for accessing a broad range of data efficiently.

When using these queries, pay particular attention to the page size and field selection in order to control the total payload to improve performance.

Some examples of the query endpoints are

Engineering

/api/v1/engineering/design_elements_query
/api/v1/engineering/design_elements_work_items_query
/api/v1/engineering/limited_design_elements_query

WBS

/api/v1/wbs/work_packages_query
/api/v1/wbs/work_orders_query
​/api​/v1​/wbs​/work_items_query
/api/v1/wbs/work_item_quantities_query

Production

/api/v1/production/production_reports_query
/api/v1/production/production_report_grid_query

Timesheets

/api/v1/time_keeping/timesheets_query
/api/v1/time_keeping/timesheet_lines_query

Invoicing

/api/v1/invoicing/invoice_items_query
/api/v1/invoicing/invoices_query

Ticketing

/api/v1/ticketing/tickets_query

Export APIs

Export APIs provide normalized data views, making them efficient for querying large datasets for business warehouses and analytics tools. They require multiple calls for complete data sets (e.g., one call for PRs, another for PRLs, etc.) but are more stable than raw APIs, as changes in the data model do not affect them.

Raw APIs

Raw APIs offer direct access to the underlying data model, useful for replicating the entire model in a business warehouse. However, they are subject to frequent changes and carry risks associated with these modifications. They serve as a last resort for accessing specific data not available through other APIs and are generally recommended for legacy support only.

Please note however that as these APIs are designed for performance and return data from the data model in its source form, the APIs are only accessible using [[access tokens|Auth.md]] assigned to an account with superuser or service level permissions and can therefore see all data.

❗️

Version Warning

Raw APIs directly query the underlying data models and are therefore subject to change. It is HIGHLY recommended that these are only used where the use case cannot be met using the _Query or Export APIs above.

To retrieve data using the raw APIs, use the endpoint in the form

/api/v1/raw/{app_name}/{model_name}

For a list of the app_name's and model_name's, use the Get Raw Models List API.

Other APIs

The typical API integration is for reporting purposes, and in these cases it is rarely unnecessary to use any APIs outside of the raw or _query APIs.

However, sometimes clients are looking to also push data into Vitruvi from other sources. In these cases, the remaining APIs not discussed above will need to be used.

The documentation for these APIs can be found in the API Reference.

Decision Guide

• Replicating Grid Data: Use _Query APIs for aggregated data in a single call.
• Business Warehouses and Analytics: Prefer Export APIs for efficient, stable access to normalized data.
• Specific Data Needs or Legacy Support: Use Raw APIs cautiously, considering their volatility and update frequency.

Other Considerations

Jobs

Some APIs allow to do batch/async processing. For example:

POST to
/api/v1/wbs/work_items/batch/

This APIs will return a job id, that then is used to get the status and response once completed:

/api/v1/core/job_status/{job id}/