17. Integration API and API keys

The integration API lets your own program, spreadsheet or script read your project data automatically: the project list, the cable and material schedules, the circuit schedule and terminal list of the distribution boards, the quantity takeoff and the plan package setup. The API is read-only: it never changes the drawing or the project.

Who can get an API key

API access is enabled per account by the operator. Once your account has access, the API keys card appears on the Profile page; without it the card is hidden. An account can have at most 5 active keys at a time.

A key sees the same projects as you do: your own, and on request the ones shared with you. For a shared project the schedules and the takeoff are only returned if the share allows exporting.

Creating a key

1. On the API keys card of the Profile page, click New key.
2. Give the key a name (for example the name of the program that will use it).
3. Choose the scope: Read projects gives the project list and project data, Read documents gives the schedules, the takeoff and the plan package. Only select what the program really needs.
4. Choose the expiry: 30, 90 or 365 days. An expired key stops working; create a new one instead.
5. Enter your current password (an account without a password needs a fresh sign-in). For your first key, accept the API usage terms.

After creation the key is shown only once: copy it and store it somewhere safe. Later the list only shows its prefix (avk_…), with the creation and expiry dates, the last use and the number of calls. We also send an e-mail notification about the new key (without the key itself).

Revoking a key

The Revoke button next to a key makes it unusable immediately; this cannot be undone. Revoke a key when you no longer use it, when you retire the program that used it, or when you suspect it has leaked.

Security tips

• Treat the key like your password: anyone who knows it can read your projects within its scope.
• Keep it in a secret store (password manager, a server environment variable or a CI secret), not in source code: never commit it to a git repository, a shared spreadsheet or an e-mail.
• Do not use it in code running in a browser (web page, browser extension): anyone can read it there. A key belongs on a server, in a script or in a desktop program.
• Give every program its own key with the narrowest scope and a short expiry, so revoking one key does not stop anything else.

Using it from a program

The key is sent in the request header as a Bearer token: Authorization: Bearer avk_…. The endpoints live under /api/v1/ (for example GET /api/v1/projects) and answer in JSON. The full description in OpenAPI format is available at /api/v1/openapi.json; most developer tools can import it.

The number of calls is limited per key and per account (by default 60 per minute and 10,000 per day); above that the server answers with 429, so wait a little. Signing in on the website (cookie) does not open the API, and a key does not sign you in to the web interface.