Skip to content

Getting started

The TeroVision API lets another system work with the cameras in a space: provision them, move them, take snapshots, record, watch live video, talk through them and manage automations. Everything goes through TeroVision at https://terovision.com.ar/api/v1, using JSON. Your integration never talks to the video server and never sees its tokens.

There is an SDK for TypeScript/JavaScript (sdk/js, Node 18 or newer) and one for Python (sdk/python, 3.9 or newer). Both retry what is safe to retry, honor Retry-After and raise a dedicated error for each case.

1. Turn on two-factor authentication

An API key outlives your session, so creating one takes more than being signed in. Without two-factor authentication enabled under Mi cuenta (My account) you cannot create keys: the panel shows a notice instead of the button, and the mobile app answers 422 two_factor_not_enabled.

2. Create a key

In the panel, inside the space, open Desarrolladores (Developers). Only owners and admins can do this. The panel asks for your password again if more than 15 minutes have passed, and every new key requires a fresh code from your authenticator app (or a recovery code).

You choose:

  • Name: it shows up in the panel and in the audit log (api:<name>), so pick one that says which system it is.
  • Maximum role: admin, member or view only. The key acts as you, with the lower of that role and whatever role you have at the time of each request.
  • Scopes: which parts of the API it can touch. See Keys and scopes.
  • Expiry (7 days to one year) and requests per minute (1 to 600, 120 by default).

The key (tv_live_<prefix>_<secret>) is shown only once. Store it as a secret, in an environment variable on your server. Every new key triggers an email to you and to the space owners — without the key itself.

3. Your first request

The key goes only in the Authorization: Bearer header. Sent in the URL, it is rejected with 400 key_in_query.

curl — resources/devportal/samples/curl/first-request.sh

export API=https://terovision.com.ar/api/v1
# The key goes only in the Authorization header. In the URL it is rejected (400 key_in_query).
curl -s -H "Authorization: Bearer $TEROVISION_API_KEY" "$API/me"
curl -s -H "Authorization: Bearer $TEROVISION_API_KEY" "$API/cameras?per_page=10"

With the TypeScript SDK:

TypeScript / JavaScript — sdk/js/examples/portal/first-request.ts

const tv = new TeroVision({ apiKey: options.apiKey, baseUrl: options.baseUrl, fetch: options.fetch });
// Run this on your server, never in a browser. In production: new TeroVision({ apiKey: process.env.TEROVISION_API_KEY! })

const me = await tv.me();
console.log(me.space.name, me.key.effective_role, me.key.scopes);

const page = await tv.cameras.list({ per_page: 10 });
for (const camera of page.data) {
  console.log(camera.id, camera.name, camera.online ? 'online' : camera.connection);
}

With the Python SDK:

Python — sdk/python/examples/portal/first_request.py

with TeroVision(api_key, base_url, transport=transport) as tv:  # run it on your server; the key is a secret
    me = tv.me()
    print(me["space"]["name"], me["key"]["effective_role"], me["key"]["scopes"])

    for camera in tv.cameras.list(per_page=10)["data"]:
        print(camera["id"], camera["name"], "online" if camera["online"] else camera["connection"])

GET /me tells you which key this is, in which space, with which scopes and which role it acts with today. If you get a 401, check the code: invalid_key, key_revoked, key_expired or creator_suspended.

4. The SDKs

  • TypeScript: sdk/js (@terovision/sdk). npm ci && npm run build produces ESM, CJS and type definitions in dist/. The package is not published on npm yet.
  • Python: sdk/python (terovision). pip install ./sdk/python (requires httpx).

Both refuse to expose the key: the TypeScript SDK won't start in a browser unless you force it, and neither includes the key in its errors or when you print the client.

What's next

  • SDK guides: cameras, PTZ, recording, video, talk, bucket, webhooks, control lease and automations.
  • API and automations: what happens when both touch the same camera.
  • REST reference: every endpoint, with its scopes and responses.