Limits and operations

This page collects the operating facts you need when you run an integration against the MultiTaction Canvus REST API in production: deadlines, throttling, list sizes, certificates, browser access and health checks.

Where the API runs

The API is part of Canvus Server and shares its HTTPS port with the web client, so an integration needs no extra port or firewall rule. Plain HTTP requests are redirected to HTTPS with 308 Permanent Redirect, which keeps the method and body. Point your integration at the https:// address directly.

Certificates

When no certificate is installed, Canvus Server generates a self-signed one. Rather than turning certificate checks off, give your integration the server's certificate or the CA that signed it:

curl --cacert canvus-ca.pem https://canvus.example.com/api/v1/server-info

requests.get(url, verify="/etc/ssl/canvus-ca.pem")

Use curl -k only for a quick test on a lab server.

Request deadlines

Canvus Server applies two fixed deadlines to API requests. They cannot be changed in the configuration.

Deadline	Length	Applies to
Response headers	120 s after your request, including any body, has been sent	Every request, including uploads and `?subscribe` streams
Whole request	300 s from the start of the request	Requests without a body, such as `GET` and `DELETE`. Requests with a body, such as uploads and JSON `POST` or `PATCH` calls, are exempt, and so are `?subscribe` streams

A request that hits a deadline returns 504 Gateway Timeout with {"msg":"Backend did not respond in time"}. A stream is open-ended once it has delivered its first message, which it normally does at once. It stays open until you close it or the connection drops.

The 300 s deadline matters most for large downloads over a slow link. If a download can take longer than 300 s, fetch it over a faster link or split the work.

Throttling

Canvus Server does not rate-limit REST API calls. Your integration is responsible for its own pace:

Prefer one ?subscribe stream over repeated polling.
Queue writes and send them at a steady rate, especially when you create many widgets.
Back off when you see 500 responses or slow replies.

Uploads

File uploads use multipart/form-data with a data part for the file and an optional json part for widget properties. Canvus Server sets no upload size limit, in the API or anywhere else on the request path, in the container, Linux package or Windows service installations. Uploads are not subject to the 300 s deadline. The practical limits are free disk space on the server, because an upload is first written in full to the server's temporary folder and then stored as an asset, and the reliability of your connection for the length of the transfer. Once the upload has arrived, the server must start its reply within 120 s. If you need a size limit, set one in a reverse proxy in front of the server. Test with the largest file you expect to send, over the slowest link you expect to use.

Lists, pagination and filtering

Only GET /audit-log is paginated. It uses a cursor: follow the URL in the Link: <...>; rel="next" response header, and set per_page to control the page size.
Every other list returns all items in one response.
Lists have no server-side search or filter parameters. GET /canvases, GET /canvases/{id}/widgets and the typed widget lists return everything your account can see. Filter in your own code.
GET /canvases/{id}/widgets?annotations=1 adds pen strokes to each widget.
The audit log is the one list with filters: created_after, created_before, target_type, target_id and author_id.

What the API does not provide

Knowing these up front saves design time:

No webhooks. Canvus Server makes no outbound calls to your systems. Follow changes with ?subscribe.
No author on widgets. Widgets do not record who created or last changed them. Track your own writes by id.
No batch or transaction endpoint. Each create, update or delete is its own request.
No widget history. The API returns current state only.
No browser cross-origin access. The API sends no CORS headers, so JavaScript on a web page served from another origin cannot call it. Call the API from a server-side process, and let your web page talk to that process.

Status codes to plan for

Status	What it means for an integration
`400`	The request is malformed or a value is out of range. Read `msg` in the body.
`401`	The `Private-Token` header is missing.
`402`	The server license is not valid. Calls on canvas content fail for every account, and non-administrators get `402` on every call.
`403`	The account lacks permission. An invalid or deleted token also returns `403` today.
`404`	The resource does not exist.
`409`	A name conflict, for example when creating or copying a canvas.
`500`	A server-side failure. Retry with back-off, then check the server logs.

See Status codes and Current behavior for the full list.

Health checks

GET /api/v1/server-info needs no authentication and returns the server version. Use it for load-balancer and monitoring probes:

curl -fsS --max-time 5 --cacert canvus-ca.pem \
  https://canvus.example.com/api/v1/server-info

A 200 response means the server is accepting API requests. The Canvus Server container image uses the same check for its own health probe.

Keep tokens safe

Store access tokens in a secret store, not in source code.
Use one token per integration, with a description that names it, so you can revoke one without touching the others.
Rotate by creating a new token before deleting the old one. See Authentication and service accounts.