Skip to main content
Belcenter AIHelp center
Administer the platform

Use the public API

Create a personal key, explore the OpenAPI documentation, and automate the same operations as in the portal.

The public API lets you automate the same business operations as the portal, within the limits of the account that owns the key.

Create a key

  1. Open your profile menu.
  2. Select API keys.
  3. Create a key and immediately store it in your secrets manager.
  4. Revoke any key that is no longer used.

A key does not grant any additional permissions. If the owner's roles or access change, API calls immediately reflect the new scope.

View OpenAPI documentation

Select API documentation from the profile menu or the keys page. Routes that the logged-in user cannot access are not displayed.

Each operation documents:

  • accepted fields and their formats;
  • mandatory values;
  • example JSON bodies;
  • possible responses and errors;
  • expected permissions.

Configure a bot using sub-resources

Bot configuration is split into specialised endpoints to prevent excessively large request bodies: identity, AI, SIP, protection, skills, and integrations. Use the sub-route corresponding to the part actually being modified.

Trigger an outbound call

The public API does not provide a direct POST /api/v1/outbound-calls endpoint. An external integration creates an outbound campaign, even if it is only calling a single contact. Pass this contact into contacts and use schedule: true to make it immediately eligible, or add scheduled_at to choose a future date.

Creation returns the IDs for the campaign and its calls. Then monitor each call with GET /api/v1/outbound-campaigns/calls/{call_id}. The scheduled status indicates queuing: it confirms neither dialling nor that the recipient answered.

The Create an outbound campaign guide includes a full JSON example. Actions initiated by bot skills use internal mechanisms tied to an existing conversation and cannot be accessed using a public API key.

Sync the language of an Odoo connection

Call POST /api/v1/bots/{id}/skills/odoo/languages with the connection parameters, or only its connectionKey if it is already saved. The response contains the active languages returned by Odoo. Then use one of the codes in connections[].executionLanguage during PATCH /api/v1/bots/{id}/skills/odoo. This language is injected into context.lang on every call and does not change the bot's language. Secrets provided to the sync route are not saved.

Upload a background image for branding

On POST /api/v1/brandings or POST /api/v1/brandings/{id}, send the image in the background multipart field, along with any other branding fields as required. The file must be a genuine, decodable PNG, JPEG, or WebP image: up to 10 MiB, 8192 pixels per side, and 8 388 608 pixels in total. A valid upload automatically activates background_style: "custom".

The response returns background_image, a local portal path, or null. This field is read-only: providing a URL or path in background_image is rejected with HTTP 400. Selecting custom with no saved image and no new file uploaded is also rejected. A preset pattern retains the image until it is explicitly deleted.

Send {"remove_background": true} to PATCH /api/v1/brandings/{id} to delete the image. If the custom background is active, Contours replaces it. A new valid file sent in the same request takes priority over this deletion. Permissions match those of branding: platform administrator or administrator of a white-label reseller within their scope. A branding used as an organisation default remains protected against complete deletion (HTTP 409).

Best practices

  • Never include a key in client-side browser code.
  • Use HTTPS.
  • Handle errors and rate limits.
  • Avoid blindly retrying creation after a network timeout: first check whether your system has already recorded the returned IDs.
  • Test on the staging environment.
  • Do not log secrets or full personal data.
Documentation updated with the application