API
REST API
Connect your software to cDESP with the X-API-KEY key: sites, ZIP export, models and regulatory documents.
4 min read
The cDESP REST API lets your software (ERP, CMMS, scripts) read and create your sites, export a site folder as a ZIP file and, depending on your subscription, read models and regulatory documents. It answers in JSON.
Getting your key
- In the left menu, click Settings.
- Scroll down to the API token card.
- Click New token.
- Click the Copy token icon to copy it. The eye icon shows it in clear text.
See also Settings.
Calling the API
- Base address:
https://api.dcrr.fr/v1 - Send the key in the
X-API-KEYheader of every request. - When you send data (
POST), send JSON with theContent-Type: application/jsonheader. - You see the sites that share at least one group with your account. See Team and groups.
- Limit: 500 requests per minute per IP address.
- Interactive reference (Swagger): https://api.dcrr.fr/swagger/index.html
First try:
curl https://api.dcrr.fr/v1/sites \
-H "X-API-KEY: YOUR_API_KEY"
List of routes
| Method | Path | Purpose | Access |
|---|---|---|---|
GET | /v1/sites | List your sites | any valid key |
GET | /v1/sites/{id} | Read one site | any valid key |
GET | /v1/sites/{id}/export/zip | Download the site folder as a ZIP file | any valid key |
POST | /v1/sites | Create a site | depends on the subscription |
DELETE | /v1/sites/{id} | Delete a site | depends on the subscription |
GET | /v1/models | List the models | depends on the subscription |
GET | /v1/models/{id} | Read one model | depends on the subscription |
GET | /v1/reglementary-documents | List the regulatory documents | depends on the subscription |
GET | /v1/reglementary-documents/{id} | Read one regulatory document | depends on the subscription |
{id} is the identifier of the object, returned in the id field.
Sites
Listing and reading
GET /v1/sites returns all your sites. GET /v1/sites/{id} returns one site.
curl https://api.dcrr.fr/v1/sites/507f1f77bcf86cd799439011 \
-H "X-API-KEY: YOUR_API_KEY"
{
"id": "507f1f77bcf86cd799439011",
"name": "North Warehouse",
"code": "000042",
"address": "12 avenue des Lilas, 75000 Paris",
"group": ["My company"],
"files": [],
"order_index": 42,
"completed": false
}
Main fields: name, code (site code, given by cDESP), address, group (groups that see the site), files (links to the files attached to the site) and completed (true when the site is marked compliant in cDESP).
Creating a site
POST /v1/sites creates a site. JSON body:
name(required): name of the site.address(required): address.group(optional): list of groups. Without this field, the site is attached to all your groups. You can only choose groups you belong to.
curl -X POST https://api.dcrr.fr/v1/sites \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "North Warehouse", "address": "12 avenue des Lilas, 75000 Paris"}'
Response 201:
{ "message": "Site created successfully", "id": "507f1f77bcf86cd799439011" }
The site code is given automatically. Some subscriptions cap the number of sites: beyond it, the response is 403. The Licence Suivi plan does not allow creating sites.
Deleting a site
DELETE /v1/sites/{id} deletes the site with its systems and their components. This cannot be undone.
curl -X DELETE https://api.dcrr.fr/v1/sites/507f1f77bcf86cd799439011 \
-H "X-API-KEY: YOUR_API_KEY"
Exporting the folder as a ZIP file
GET /v1/sites/{id}/export/zip returns a ZIP file: site documents, inspection reports (inspection plan, VI, IP, audit) with their signed version, and photos of the systems.
curl https://api.dcrr.fr/v1/sites/507f1f77bcf86cd799439011/export/zip \
-H "X-API-KEY: YOUR_API_KEY" \
-o site.zip
The list of pressure equipment in scope (list 6-III) is not produced by the API: the ZIP holds an empty file in its place that says so. Generate this list from cDESP. See Site folder.
Models
GET /v1/models returns the catalogue of equipment models. GET /v1/models/{id} returns one model.
curl https://api.dcrr.fr/v1/models \
-H "X-API-KEY: YOUR_API_KEY"
Each model holds id, designation, files (attached files) and doc_files (documentation).
Regulatory documents
GET /v1/reglementary-documents returns the list of regulatory documents. GET /v1/reglementary-documents/{id} returns one document.
curl https://api.dcrr.fr/v1/reglementary-documents \
-H "X-API-KEY: YOUR_API_KEY"
Each document holds id, name, file (link to the file), created_at and updated_at.
Errors
| Code | Case | Sample response |
|---|---|---|
400 | Invalid request body, name or address missing | {"error": "Le nom et l'adresse sont obligatoires"} |
401 | Key missing or unknown | {"message": "Invalid or missing API Key"} |
401 | Your subscription does not allow this route | {"message": "You are not allowed to do this request"} |
403 | Site not shared with your groups, or subscription limit reached | {"error": "You don't have access to this site"} |
429 | More than 500 requests in one minute | {"message": "Too many requests, please slow down"} |
500 | Server error, or site not found when reading | {"error": "Failed to retrieve site: ..."} |
Error messages are in English or French. Test the HTTP code rather than the text.