API and webhooks
Cable data API for website, shop, and PIM.
Through the API, your systems fetch what is in the portal: every published cable with its data, images, datasheet, and cross-section drawing.
Who it's forFor IT leads, developers, and web agencies.
In short
- Read: cables, data, images, and datasheets
- Order: images without opening the portal
- Webhooks: signed messages when something changes
- Keys with permissions, described in OpenAPI
Your system asks
GET /api/v1/cables/rg58Authorization: Bearer cbl_…The portal responds
{"slug": "rg58","name": "RG 58 C/U","technical": [{"kind": "field","label": "Characteristic impedance","value": { "kind": "text", "text": "50 Ohm" }}],"assets": [{"url": "https://portal.example/…/rg58.png",… more fieldsYour product page
What is the API?
What it is
The API is the interface your own systems use to fetch cables, data, and images from the portal.
Your cables exist once, in the portal. Your website, shop, and PIM ask the portal instead of maintaining their own copies. A PIM is the system where a company collects its product data.
Key terms
- API
- A URL that a program calls and that responds with data, not with a page for people.
- API key
- A secret string your system uses to identify itself. It belongs to exactly one company in the portal.
- Permission
- What a key is allowed to do: read, write, or order. You choose it when you create the key.
- Webhook
- A message the portal sends on its own to a URL on your system as soon as something happens.
- OpenAPI description
- A file that describes every call and every field of the API in machine-readable form.
How does the data get into my system?
How it works
Your server makes a request with a key, and the portal responds with data and later reports what changes.
The example shows reading one cable. Ordering works the same way: request, respond, notify.
The process as six stations on one line: you create a key. Your system requests a cable, the portal delivers data and URLs, and your system displays them. Later the portal reports a change, and your system fetches what changed.
YouYour systemThe portal
YouCreate a key
Your systemRequest cables
The portalDeliver data and URLs
Your systemShow it on your site
The portalReport changes by webhook
Your systemFetch only what changed
Step by step
- Step 1 of 6: You
Create a key
An owner creates a key in the portal and chooses its permissions. The portal shows the key exactly once.
- Step 2 of 6: Your system
Request cables
Your server fetches the list or a single cable. It sends the key in the request header.
- Step 3 of 6: The portal
Deliver data and URLs
The response is JSON: technical data, sizes, and the URLs of images, cross-section drawings, and the datasheet.
- Step 4 of 6: Your system
Show it on your site
Your system stores the data. It embeds images and drawings directly by URL.
- Step 5 of 6: The portal
Report changes by webhook
When a cable is published, changed, or withdrawn, the portal sends a signed message to your URL.
- Step 6 of 6: Your system
Fetch only what changed
Your system verifies the signature and fetches just that cable again.
The same process as a drawing
The drawing shows the path from the portal through the API to your website.
The API for website, shop, and PIM
- Cables, data, and images are in the portal.
- The manufacturer's system calls the API with its own key.
- Image and data are on the website; a webhook reports changes.
Portal, portal with API, developer or platform partner: which access fits you is on one page. Which access fits? →
What is in a response?
What the API returns
One call returns a cable with everything public that belongs to it: data, sizes, and the URLs of its files.
At the top are a real request and its shortened response. Below is what a product page does with it. Lists are paginated, with up to 100 entries per page.
At the top, a request for one cable with the key in the header, and the response as JSON with technical data, images, sizes, and the datasheet's URL. Below it, a product page that uses them to show the image, data, and downloads.
Your system asks
GET /api/v1/cables/rg581Authorization: Bearer cbl_…The portal responds
{"slug": "rg58","name": "RG 58 C/U","technical": [{2"kind": "field","label": "Characteristic impedance","value": { "kind": "text", "text": "50 Ohm" }}],"assets": [{3"url": "https://portal.example/…/rg58.png","width": 1600, "height": 1067,"contentHash": "9f2c7d0b…",… more fields}],"variants": [{4"outerDiameterMm": 4.95,"crossSectionUrl": "https://portal.example/…/rg58.svg","webModelUrl": "https://portal.example/…/rg58.glb",… more fields}],"datasheetUrl":5"https://portal.example/api/v1/cables/rg58/datasheet",… more fields}Your product page
More cables from the list
What the numbers show
The request
One URL per cable and the key in the header. A read call needs nothing more.
Technical data
An ordered list of labels and values, in the same order as the datasheet.
Images with a fixed URL
Every approved file comes with its URL, its size in pixels, and a checksum. The checksum changes when the file does.
Sizes
Every row of the table with its outer diameter, cross-section drawing, and 3D model, where available.
Datasheet
The cable's finished PDF has its own URL. This call needs the key too.
Read, write, or order: which permission does my key need?
The three permissions compared
Read is enough for a website, shop, or PIM; give write and order only to the system that needs them.
Write and order include read. One key can have both permissions at once.
The form for a new key in the portal: a name, three checkboxes for the read, write, and order permissions, and an optional monthly budget. Below it, a note that the key is shown only once.
New key
- ReadFetch cables, families, files, and cable requests
- WriteAlso create a cable request
- OrderAlso get prices, order images, and retrieve them
cbl_••••••••••••The key is shown only once.
| Aspect | Read | Write | Order |
|---|---|---|---|
| What the key can do | Fetch cables, families, files, and cable requests | Also create a cable request | Also get prices, order images, and retrieve them |
| Typical use | A website, shop, or PIM shows your cables | Your system submits a new cable for modeling | The shop orders a missing image itself |
| Budget per key | Not needed for read | Not needed for write | Optional, per month or in total |
| For an agency's guests | Yes, if an owner grants read | No | Yes, if an owner grants order |
More on this Order an image yourself in the demo portal →
What do I gain from the API, and where are its limits?
Advantages and limits
The API keeps all your systems in sync, but it reads only what is published and needs someone who writes code.
Advantages
One source for all systems
What is published in the portal is the same on your website, in your shop, and in your PIM.
Embed files directly
Public images and drawings each have their own URL. Your website embeds them without copying them.
Ordering without duplicates
An order sent twice is carried out only once. If the price differs from the one you expected, nothing is ordered.
Keys with narrow permissions
Every key has its own permissions and an optional budget. An owner can revoke it at any time.
Signed messages
The signature tells your system that a message comes from the portal. The portal retries failed messages several times.
Machine-readable description
The OpenAPI description and the documentation, with an example for every call, are publicly available.
Limits
Server to server only
A browser can't call the API. That way, no key ends up in a page's source code.
Published content only
Read calls return published cables and approved files. Drafts and archived cables are not included.
No publishing through the API
You change and publish cables in the portal. Write only creates a cable request.
Catalog inquiries as a notice only
A webhook reports that an inquiry has come in. You read the name and text in the portal.
Not every change is reported
Changed type data triggers a message. Changes to sizes and images don't trigger one yet.
A limited number of calls
A key can send 100 calls in a row. After a pause of 10 seconds, the portal starts counting again.
No ready-made shop extension
There is no plugin for any shop system. Your IT team or your agency writes the integration.
Not the right tool if:
- Nobody at your company or your agency writes code; in that case, embed the finished catalog in your website.
- You want the data loaded directly from the browser.
- You want your system to create, change, or publish cables itself.
How is this different from transferring data by hand?
Compared with today
Today someone maintains every copy separately; with the API, there is only the original.
Today, a person enters the data by hand into the website, shop, and PIM, and two of the three copies are outdated. With the API, all three systems fetch the same version from the portal.
Until now
Transfer by hand
Data versionAs old as the last copy
With the API
API
Data versionAlways what's in the portal
| Aspect | Transfer by hand | Files by email | API |
|---|---|---|---|
| Data version | As old as the last copy | As of the day it was sent | Always what's in the portal |
| A new image | Someone downloads it and uploads it again | Someone sends it again | Your system fetches it by URL |
| Source of errors | Typos and forgotten cables | Old files stay in circulation | No copy, no copying errors |
| Effort per cable | By hand every time | An email every time | None after setup |
| Setup | None, just time | None, just an inbox | Write the code once |
What do I need, and what does it cost?
What you need and what it costs
You need published cables, a plan that includes the API, and a server that sends the calls.
What you need
Published cables
The API returns what is published in the portal. Without published cables, the list stays empty.
A plan with the API
The API and webhooks are not included in every plan.
An owner for the keys
Only owners create keys and webhooks. A company can have at most 10 webhook endpoints.
Your own server
The calls come from your server, never from your visitors' browsers.
A public URL for webhooks
The portal sends messages only to an encrypted URL that is reachable from the internet.
Someone who writes code
Your IT team or your agency writes the integration once. The OpenAPI description helps.
What it costs
Read calls cost nothing. Images your system orders cost the same as in the portal and appear on the monthly invoice. Whether the API and webhooks are included depends on your plan.
What else do people ask?
Frequently asked questions
Short answers to the questions developers usually still have before they start.
- Is the API included in every plan?
- No. Whether the API and webhooks are included depends on your plan.
- Can we call the API directly from the browser?
- No. The API is designed for server-to-server calls, so no key ends up in the browser.
- Can cables be published through the API?
- No. You publish in the portal; the API returns what is published and reports it by webhook.
- Where can we find the documentation?
- In the portal under the API settings, with an example for every call. The OpenAPI description is available without a key.
- What happens if our server misses a webhook?
- The portal retries the message several times at increasing intervals. After that, it is in the log, and an owner can resend it manually.
- How do we verify that a message comes from the portal?
- Every message carries a signature computed from your secret, the timestamp, and the content. Your server recomputes it and discards old messages.