Ayonix Video Analytics

Developers

Video analytics API: integration principles and access

In short

This page describes the principles that apply to retrieving analytics data over HTTP — authentication, the request lifecycle, pagination, rate limiting, versioning and error handling. Ayonix does not publish a public API specification; concrete endpoints and schemas come with evaluation access.

Scope

What is on this page, and what needs access

Published here

  • The conceptual request and response lifecycle for retrieval integrations
  • Authentication and credential-handling principles
  • Pagination, rate limiting and error-handling principles
  • Versioning expectations and how to avoid being broken by a change

Requires evaluation access

  • Endpoint paths, parameter names and response schemas
  • Authentication scheme details and token lifetimes
  • Rate limit values and quota policy
  • Available data types and retention windows for your deployment

No endpoint path, class name, method signature or response shape appears anywhere on these pages. Ayonix does not publish a public interface specification, and documenting an invented one would waste your engineering time building against a contract that does not exist.

Conceptual request lifecycle

A retrieval integration follows the same shape regardless of the specific contract. Designing against this shape before you have the specification means the implementation is mostly ready when access arrives.

  • The client authenticates with credentials held server-side and receives or presents a token
  • The client requests a data type over a bounded time range, scoped to cameras or sites it is authorised for
  • The response returns a page of results with a continuation marker where more exist
  • The client follows continuation markers until the range is complete
  • Transient failures are retried with bounded backoff; client errors are not retried
  • The client records what it successfully ingested so a later run can resume rather than duplicate

Authentication principles

The commonest serious failure in integrations of this kind is credential exposure, and it is almost always avoidable.

  • Credentials are held server-side only — never in a browser, mobile app or any client the user controls
  • Credentials are stored in a secrets manager rather than in configuration files or environment files committed to a repository
  • Rotation is designed in from the start, with the integration able to accept a new credential without downtime
  • Each integration gets its own credential so access can be revoked individually
  • Access is scoped to the minimum data the integration needs

Pagination, rate limiting and backpressure

Analytics data volumes grow quickly with camera count and reporting granularity. Integrations that assume one response contains everything fail silently as the deployment grows.

  • Always follow continuation markers; never assume a single response is complete
  • Request bounded time ranges rather than open-ended history
  • Respect rate limits and back off rather than retrying immediately on a limit response
  • Process asynchronously so a slow consumer does not hold connections open
  • Schedule bulk backfill outside peak periods

Error handling and idempotency

Retrieval integrations should be safe to re-run. That single property removes most operational pain when something goes wrong at three in the morning.

  • Distinguish transient errors, which should be retried with backoff, from client errors, which should not
  • Make ingestion idempotent on a stable record identifier so a re-run does not duplicate data
  • Record a high-water mark so a resumed run continues rather than restarting
  • Surface persistent failures as an operational alert rather than logging them silently
  • Include a request identifier in your logs so a failure can be traced with Ayonix support

Versioning

Agree the versioning and deprecation policy before building against an interface. This is a contractual question as much as a technical one.

  • Pin the interface version your client targets rather than tracking whatever is current
  • Agree the deprecation notice period in writing as part of the access agreement
  • Treat an unexpected schema change as an incident, not as something to patch around silently
  • Test against a new version before switching production traffic to it

Frequently asked questions

Why are there no endpoint paths on this page?

Because Ayonix does not publish a public API specification and none has been verified. Documenting invented endpoints would waste your engineering time building against a contract that does not exist. Request access and build against the real definition.

Can we poll for alerts?

You can, but you should not. Polling adds latency and load for a job that push delivery does better. Use webhook or VMS delivery for alerting and retrieval for reporting, reconciliation and backfill.

How do we handle a missed period after an outage?

Record a high-water mark, make ingestion idempotent on a stable record identifier, and re-run the range. An integration designed this way recovers from an outage without anyone deduplicating data by hand afterwards.

Other developer pages

Author
Gabriel Bamola, Chief Marketing Officer, Ayonix
Technical review
Dr Sadi Vural, Founder and Chief Executive Officer, Ayonix
Published
Last reviewed

Request evaluation access

Evaluation access includes the interface documentation, licensing details and supported-platform information that this site deliberately does not publish. Tell us what you are building and an engineer will scope it with you.

Request API evaluation access Read the architecture guidance