{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"1cb89cf7-0337-415a-b04f-deef5874cc8c","name":"Singular REST API and Data Stream API v1.0","description":"## Singular REST API\n\nThis is the command collection for the Singular REST API v1.0.\n\nThe easiest way to get started with the API is to click the [_Run in Postman_](https://www.getpostman.com/docs/run_button_ux) button present at the top of the documentation page and use the Postman App to send requests.\n\nAlso visit the [Singular Developer Portal](http://developer.singular.live/) for further documentation of Singular APIs and SDKs, including examples and code snippets.\n\n## Overview\n\nUse the Singular REST API to programmatically send and receive data and trigger animations from Singular overlays.\n\nThis API provides access to a variety of resources, including the following:\n\n- [App Instance API](#193ac6f2-60d7-40dd-a729-0650ab8bd990) \n- [Data Node API](#f2901dee-52ef-4963-98da-e0eab59857b2)\n- [Data Streams API](#59563b90-8f36-453e-9f14-ee71d05813ff)\n\nIf you plan to integrate Singular into your platform, let us know! We provide additional REST endpoints for Singular integration partners.\n\n- Want to join the Singular Technology Partner Program? Click [here](https://www.singular.live/technology-partners)!\n- Want to become a Singular Certified Partner? Send an email to [mike(at)singular.live](mailto:mike@singular.live).\n\n## Authentication\n\nThe Singular API supports various authentication options depending on the function you call.\n\n- **Basic authentication:**\n  All endpoints and queries can use “Basic Authentication” with username and password.\n\n- **Tokens:**\n  `Tokens` are used as path variables in the query URL. Requests using `Tokens` require no authentication and support calls for sending data and trigger animations.\nUsers can generate `Tokens` for App Instances and Data Nodes in the Singular Dashboard. The article [Generate and revoke access to your Control App](https://support.singular.live/hc/en-us/articles/360046167591-Generate-or-revoke-access-to-your-Control-Application) on the [Singular Support Portal](https://support.singular.live) contains a step-by-step description.\n\n- **Private and Public Tokens:**\n  [Singular Data Streams](#59563b90-8f36-453e-9f14-ee71d05813ff) use Private and Public Tokens for sending data and receiving data.\n\n# Frequently used endpoints\n\nThe most frequently used endpoints are listed below. You may check them out first!\n\n- Update “Show Data” in a Singular overlay\n    - [Send Show Data using basic authentication](#857fc25f-57b6-4720-b720-e9e6a015de5a)\n    - [Send Show Data using a shared token](#cef7adce-b17f-4b96-bab3-02d9d7539683)\n\n- Trigger animations of a Singular overlay\n    - [Trigger animation using basic authentication](#f235ab4e-a35c-4440-ac8d-13fc73118044)\n    - [Trigger animation using a shared token](#0db6fd38-87d3-4938-8ea7-8523cedef64a)\n\n- Update “Global Data” in Singular data nodes\n    - [Send Global Data using basic authentication](#98e9c2d5-f3d3-4aae-9672-70f2fc0aee8a)\n    - [Send Global Data using a shared token](#43b61d6b-c0b1-427f-a327-bfe732332355)\n\n# Rate limits\n\nEvery day the Singular API receives millions of requests. To help manage the volume of requests, limits are placed on the number of requests that can be made. The Singular API also employs several safeguards against bursts of incoming traffic. Users who send many requests in quick succession or a high volume of data that exceed their account limits may see error responses that show up as [status code 429](https://tools.ietf.org/html/rfc6585).\nThese limits help us provide the reliable and scalable API that our customers need.\n\nWe have several limiters in the API, including:\n\n- **Daily limiters** limit the number of requests and the amount of data received by the API per day.\n\n- **Burst rate limiters** limit the number of requests and the amount of data received by the API per minute.\n\nThe daily and burst rate limiters depend on your subscription type.\n\n**Rate limits for Enterprise subscriptions**\n\n|                    | Daily API Limit | Burst API Limit (per minute) |\n|--------------------|:---------------:|:----------------------------:|\n| Number of Requests | 100,000 calls   | 500 calls                    |\n| Amount of Data     | 500 MB          | 1 MB                         |\n\n\n**Rate limits for Professional and Non-Profit subscriptions**\n\n|                    | Daily API Limit | Burst API Limit (per minute) |\n|--------------------|:---------------:|:----------------------------:|\n| Number of Requests | 20,000 calls    | 200 calls                    |\n| Amount of Data     | 100 MB          | 500 KB                       |\n\n\n**Rate limits for Free subscriptions**\n\n|                    | Daily API Limit | Burst API Limit (per minute) |\n|--------------------|:---------------:|:----------------------------:|\n| Number of Requests | 5,000 calls       | 25 calls                     |\n| Amount of Data     | 25 MB           | 100 KB                       |\n\nTreat these limits as maximums and don’t generate unnecessary load. See Handling Rate Violations for advice on handling 429s. If you suddenly see a rising number of rate-limited requests, please contact [support(at)singular.live](mailto:support@singular.live).\nWe may reduce limits to prevent abuse or increase limits to enable high-traffic applications. To request an increased rate limit, please contact [support(at)singular.live](mailto:support@singular.live).\n \nFor integrating data feeds with high-volume, high-frequency, and low-latency updates, we recommend using Singular Data Streams -> Add link to Singular Data Streams\n\n## Endpoints using rate limits\n\n- **PUT / PATCH:** https://app.singular.live/apiv1/appinstances/:{app_instance_id}/control \n- **PUT / PATCH:**  https://app.singular.live/apiv1/control/:{app_access_token}\n- **PUT / PATCH:**  https://app.singular.live/apiv1/datanodes/:{datanode_id}/data\n- **PUT / PATCH:**  https://app.singular.live/apiv1/datanodes/:{datanode_token}/data\n\n## Header response codes\n\nRequests to endpoints using rate limits return custom headers response codes. The response code is a JSON string with detailed information about daily limits and burst limits. \n\n- **X-Singular-Ratelimit-Burst-Calls**\n\n**`{\"limit\": 500,\"remaining\": 499,\"reset\": 1614430792}`**\n\n| Property    | Description |\n|-------------|:------------|\n| `limit`  | maximum number of requests per minute |\n| `remaining`  | number of calls left within the current minute |\n| `reset`  | UTC time indicates the next reset of the burst limit |\n\n- **X-Singular-Ratelimit-Daily-Calls**\n\n**`{\"limit\":1048576,\"remaining\":1048452,\"reset\":1614430792}`**\n\n| Property    | Description |\n|-------------|:------------|\n| `limit`     | maximum number of requests per day |\n| `remaining` | number of calls left for the current day |\n| `reset`     | UTC time indicates the next reset of the daily limit |\n\n- **X-Singular-Ratelimit-Burst-Data**\n\n**`{\"limit\":100000,\"remaining\":99854,\"reset\":1614470401}`**\n\n| Property    | Description |\n|-------------|:------------|\n| `limit`     | maximum amount of data in byte per minute |\n| `remaining` | amount of data in byte left within the current minute |\n| `reset`     | UTC time indicates the next reset of the burst limit |\n\n- **X-Singular-Ratelimit-Daily-Data**\n\n**`{\"limit\":524288000,\"remaining\":522565096,\"reset\":1614470401}`**\n\n| Property    | Description |\n|-------------|:------------|\n| `limit`     | maximum amount of data in byte per day |\n| `remaining` | amount of data in byte left for the current day |\n| `reset`     | UTC time indicates the next reset of the daily limit |\n\n## Common causes and mitigation strategies\n\nRate limits can occur under a variety of conditions, but it’s most common in these scenarios:\n\n- Running a large volume of closely-spaced requests can lead to the burst rate limiting. This often happens when developing or testing a data feed integration. When engaging in these activities, you should try to control the client side's request rate and data volume (see Handling Rate Limit Violations).\n\n- Sending huge amounts of data to the API can lead to the burst rate limiting. This happens when sending growing statistics data over a period of time. In such a case, you should control the data volume on the client-side and only send the required dynamic data to the API.\n\n## Rate limit violations\n\nRate limit violations are logged to the [Account Usage Statistics](https://app.singular.live/users/settings/accountStatus).\n\n> Rate limit violations for **Professional and Enterprise Subscriptions** are logged, but API requests exceeding the limits will still be processed.\n\n> Rate limit violations for **Free Subscriptions** will be logged, and API requests exceeding the limits will be rejected and return an [error status code 429](https://tools.ietf.org/html/rfc6585) `Too Many Requests`\n\n## Handling rate limit violations\n\nA basic technique for integrations to handle rate limiting is to watch for `429 status codes` and build in a retry mechanism. The retry mechanism should follow an exponential backoff schedule to reduce request volume or increase the time between requests when necessary. Ideally, the client-side is self-aware of existing rate limits and can pause requests until the currently exceeded window expires.\n\nWe’d also recommend looking into the following techniques for handling limiting gracefully:\n- Add randomness into the requests to avoid a [thundering herd problem](https://en.wikipedia.org/wiki/Thundering_herd_problem).\n- Implement a [token bucket algorithm](https://en.wikipedia.org/wiki/Token_bucket) for controlling rate limits at a global scale.\n\n## Support\n\nFor help regarding accessing the Singular REST API, feel free to drop in a line at [support(at)singular.live](mailto:support@singular.live).\n\n## Terms of Use\n\nFor information on API terms of use and privacy, refer to our policy document at [http://www.singular.live/terms-of-service](http://www.singular.live/terms-of-service) and [http://www.singular.live/privacy-policy](http://www.singular.live/privacy-policy).","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"2177855","team":82768,"collectionId":"1cb89cf7-0337-415a-b04f-deef5874cc8c","publishedId":"TWDdiDPV","public":true,"publicUrl":"https://documenter-api.postman.tech/view/2177855/TWDdiDPV","privateUrl":"https://go.postman.co/documentation/2177855-1cb89cf7-0337-415a-b04f-deef5874cc8c","customColor":{"top-bar":"FFFFFF","right-sidebar":"555555","highlight":"58b947"},"documentationLayout":"classic-double-column","customisation":null,"version":"8.11.4","publishDate":"2022-12-27T20:38:33.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/2a500e7404ff853b3c8252ea9221b8f0ce98a4e27d82c6355ded0c97e6123e8b","favicon":"https://res.cloudinary.com/postman/image/upload/v1569356740/team/sb53qfuqrhdm0bycgouv.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/TWDdiDPV"}