Getting Started

Poly Lens API Overview

The Poly Lens API gives you programmatic access to the same management and insights data available in the Poly Lens Admin Portal. Use it to manage accounts, device inventory, device configuration, gather analytics, and more. For a full list of supported devices see Poly Lens Supported Devices.

The Poly Lens API is intended for authorized partners and developers with existing Poly Lens accounts. You must have admin permissions within a tenant to create API credentials.

How the API Works

The Poly Lens API is built on GraphQL, a query language designed for requesting exactly what you need, across related objects, in a single request. If you're coming from REST APIs, here are the core differences to understand before you start.

Three endpoints

With a traditional REST API, each resource has its own endpoint.

The Poly Lens API uses three endpoints: one for authentication, one for queries/mutations, and one for subscriptions. Every read and write operation goes through the endpoint; the query or mutation you send (in the request body) changes between requests.

You define the response shape

Typically, REST API endpoints have a fixed response shape.

With GraphQL, you specify which fields you want. If you only need a device's id and connection status, you only ask for (and receive) those. This matters for performance, especially when working with large device inventories.

Data is relational

The queries reflect the inherently relational data structure: tenants contain accounts, accounts contain sites, sites contain rooms, and rooms contain devices.

A single GraphQL query can traverse this entire hierarchy and return exactly what you need in one request. This reduces the need to chain multiple calls together, but highlights the importance of only asking for the data you need in each request.

Queries vs Mutations

• Queries are read operations equivalent to GET
• Mutations are write operations equivalent to POST, PUT, and DELETE
• Subscriptions are real-time listeners for data changes. There isn't a direct REST equivalent.

Errors

Unlike REST, GraphQL can return a HTTP 200 OK when an operation fails. This isn't just a quirk, it's by design. A single GraphQL request can span multiple operations, so part of the response can succeed while another part fails.

Errors are surfaced inside the response body under an errors array. Adjusting your error handling to check for this is important; it's best practice not to rely solely on HTTP status codes.

Note

If you're new to GraphQL, graphql.org has a solid introduction. The API Playground is also a great way to get hands-on before writing any code. No token management is required. Just sign in and start querying.

API Credentials

API Credentials (client_id and client_secret) are the identity your application uses to authenticate with the Poly Lens API. Every API request requires a valid bearer token, and that token is obtained by exchanging your credentials at the authentication endpoint.

Credential creation and management requires Administrator permissions. Each tenant can have multiple sets of credentials, each scoped to one or more accounts and assigned a role that controls what data it can access.

Note

These credentials are not tied to your SSO (Single Sign-On) user account. API requests authenticate using the generated client_id and client_secret, not your SSO username or identity provider (IdP) session.

To manage API Credentials, log in to the Poly Lens Admin Portal, select the Account dropdown » Account Settings » API Credentials

Create API Credentials

1. Select Add New.
2. Select the data scope for the credentials (Just this account or Multiple accounts).
3. Enter a Name and Role and select Confirm. The new credentials display in the list.

Edit API Credentials

1. Select a credential set from the list (this enables the Edit button).
2. Select Edit.
3. Edit the credentials as needed and select Confirm. The API credentials are updated.

Delete API Credentials

1. Select a credential set from the list (this enables the Delete button).
2. Select Delete.
3. Select Delete to confirm. The API credentials are deleted from the account and removed from the list.

Connecting to the API

There are three URLs you'll use when integrating Poly Lens APIs into your applications:

# Authentication Endpoint to retrieve `access_token` (OAuth 2.0)
POST https://login.lens.poly.com/oauth/token

# GraphQL API Endpoint (Queries/Mutations)
https://api.silica-prod01.io.lens.poly.com/graphql

# GraphQL API Endpoint (Subscriptions)
wss://api.silica-prod01.io.lens.poly.com/graphql

Generating an access_token

The Poly Lens API GraphQL Endpoint requires an authorization header with a valid bearer token on every request.

Note

The token format is standard OAuth 2.0: authorization: Bearer <access_token>.

The API is served over HTTP/2, which requires lowercase header names (RFC 7540). Use authorization, not Authorization (HTTP/1.1 convention).

The access_token is a signed JWT (JSON Web Token) that identifies your API credentials and cryptographically proves their authenticity. Tokens are valid for 24 hours. Once expired, you must request a new one.

To obtain an access_token, send a POST request using the OAuth 2.0 client_credentials grant, exchanging your Client ID and Client Secret.

If you're not wrapping this step into your code flow, you can use the pre-populated cURL request from the Lens Admin Portal:

1. Log in to the Poly Lens Admin Portal, select the Account menu > Account Settings > API Credentials.
2. Select a Client ID from the list and a Sample Code modal appears.
3. Click anywhere in the cURL sample to copy it to your clipboard.
4. Paste the cURL request into your terminal or API tool of choice:

curl --request POST \
  --url https://login.lens.poly.com/oauth/token \
  --header 'Content-Type: application/json' \
  --data '{"client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "grant_type": "client_credentials"}'

On Windows Command Prompt, replace \ with ^

After sending the request, you should receive an HTTP 200 OK response:

{
  "access_token": "your-access-token",
  "token_type": "Bearer",
  "expires_in": 86400
}

The API Playground

The API Playground lets you run live GraphQL queries against your authorized Poly Lens tenants. It's the fastest way to explore the schema, prototype queries, and inspect response structures before writing any code.

Sessions time out after 1 hour. If you see schema or authorization errors, refresh the page to re-authenticate and continue.

Using the API Playground

Unlike direct API requests, which require a bearer token in every request, the API Playground authenticates using your existing Poly Lens user login. There's no token management or headers to configure; just sign in and start querying.

By default, the API Playground is scoped to your authenticated user's access. If your user has access to multiple tenants, queries that don't require a tenantId parameter will return data from all tenants you're authorized to access.

To scope queries to a single tenant, toggle Use Client Credentials on and select a credential set from the dropdown. This is useful when you want to test queries under the same access scope your application will use in production.

The API Playground is divided into three main sections:

• Left: The Schema Explorer, which shows all available Root Types (query, mutation, and subscription). Selecting a Root Type displays all available Fields. Select a Field to see the Arguments, Fields, and Types for the object.
• Middle: Where you'll write GraphQL Queries, add variables, and run the operation.
• Right: Displays the Response Object, the HTTP Response Status, and the option to display the response as JSON or in a table.

Pagination and Performance

Some queries, like deviceSearch, can return large and deeply nested responses due to the number of fields and subfields involved. This increases the processing load on the server and can slow down response times.

As a best practice, always request only the data you need. When constructing large or complex queries, implementing pagination helps improve performance by reducing payload size and server processing load, resulting in faster response times and a lower risk of exceeding the query cost limit.

Queries that support pagination include a pageInfo object, which provides four metadata fields:

• totalCount: The total number of results
• countOnPage: The number of results returned in the response
• nextToken: The token to retrieve the next page
• hasNextPage: True if there are more results available

Implementing Pagination

1. Add the pageInfo fields to your query.
2. Add nextToken: null to the parameters of the initial query (passing null on the first set indicates the start of a results set).
3. Run the query. If hasNextPage: true, then nextToken will contain a value.
4. Pass the nextToken value into the parameters of the next query.
5. Repeat this process until hasNextPage: false and/or nextToken: null.

Query Cost Model

The Poly Lens API uses a query cost model to encourage efficient GraphQL queries and protect the API from excessive load. Each query or mutation is assigned a calculated cost based on the complexity and depth of the operation. More deeply nested queries cost more than shallow ones.

Cost data is available on every request. Use it during development to understand the cost of your queries before implementation, or in production to monitor usage and avoid hitting the query cost limits.

calculateQueryCost: Inspect query cost directly in the response body. Useful for prototyping in the API Playground and during development.

HTTP Response Headers: Every response includes graphql-ratelimit-querycost, ratelimit-limit, ratelimit-remaining, and ratelimit-reset. Useful when cost monitoring is implemented in a centralized request layer (not individual functions).

Cost Limits

Parameter	Value
Per-query cost limit	10,000 points
Rolling balance	100,000 points
Reset interval	60 seconds

Each request must stay below the 10,000 point limit. Requests that exceed the limit are rejected; see exceeding the cost limit for error response structure. Queries under the limit are deducted from the 100,000 point rolling balance. The balance resets every 60 seconds, regardless of how many points have been used.

Checking Query Cost

Add calculateQueryCost as a root level field in any query or mutation to inspect its cost before or during implementation:

query TenantsICanAccess {
  calculateQueryCost {
    queryCost
    costUsed
    costRemaining
    secondsToReset
  }
  tenants {
    id
  }
}

Exceeding the Cost Limit

Exceeding the cost limit returns an HTTP 400 Bad Request with the following error structure:

{
  "errors": [
    {
      "message": "GraphQL query cost of xxxx points exceeds maximum cost limit of 10000 points."
    },
    {
      "extensions": {
        "code": "INTERNAL_SERVICE_ERROR",
        "stacktrace": [
          "GraphQLError: GraphQL query cost of xxxx points exceeds maximum cost limit of 10000 points.",
          ... //truncated for brevity
        ]
      }
    }
  ]
}

calculateQueryCost Example

The following query fetches device inventory with calculateQueryCost included to demonstrate cost inspection.

Query:

query Inventory($params: DeviceFindArgs, $tenantId: ID!) {
  calculateQueryCost {
    queryCost
    costUsed
    costRemaining
    secondsToReset
  }
  tenant(id: $tenantId) {
    id
    name
    inventory {
      deviceSearch(params: $params) {
        edges {
          node {
            id
            name
            connected
            lastDetected
            lastConfigRequestDate
            site {
              id
              name
            }
            room {
              id
              name
            }
          }
        }
      }
    }
  }
}

Response:

{
  "data": {
    "calculateQueryCost": {
      "queryCost": 6505,
      "costUsed": 16457,
      "costRemaining": 83543,
      "secondsToReset": 12
    },
    "tenant": {
      ... //truncated for brevity
  }
}

In this example, the query executed cost 6,505 points. 16,457 points have been used and 83,543 remain. The balance resets in 12 seconds.

---

If you have questions about usage, authentication, or integration with the Poly Lens APIs, contact us.