This is the public REST API for elmah.io. All of the integrations communicates with elmah.io through this API.

For additional help getting started with the API, visit the following help articles:

• [Using the REST API](https://docs.elmah.io/using-the-rest-api/)
• [Where is my API key?](https://docs.elmah.io/where-is-my-api-key/)
• [Where is my log ID?](https://docs.elmah.io/where-is-my-log-id/)
• [How to configure API key permissions](https://docs.elmah.io/how-to-configure-api-key-permissions/)

Api Documentation

IOTVAS API enables you to discover IoT/Connected devices in the network and provides detailed real-time risk analysis, including firmware vulnerability analysis without requiring the user to upload the firmware file. Please visit the [signup page](https://iotvas-api.firmalyzer.com/portal/signup) to create an API key. IoTVAS API can be easily integrated with vulnerability scanning and network port scanner tools. For example, we have also released the [IOTVAS NSE script](https://github.com/firmalyzer/iotvas-nmap) that turns the nmap port scanner to a IoT/connected device discovery and real-time risk assessment tool. For more infromation on IoTVAS and other solutions please visit [Firmalyzer web site](https://www.firmalyzer.com).

Provides a way for apps to subscribe to certain change events in HubSpot. Once configured, apps will receive event payloads containing details about the changes at a specified target URL. There can only be one target URL for receiving event notifications per app.

The iQualify API offers management responses for building learning experiences using your iQualify instance data. Once you’ve registered with iQualify, you can request an API access token by navigating to the API access section of the "Account Settings" area. Find out how to [Request your API access token](https://www.iqualify.com/help/connecting-iqualify-to-other-systems/api/how-to-access-and-manage-your-api-token) on our Knowledge base. All endpoints are only accessible via https and are located at api.iqualify.com. For instance: you can find your current offerings by accessing the following URL: https://api.iqualify.com/v1/offerings/current

This API allows to config/change/delete Internet Exchange services. # Filters When querying collections, the provided query parameters are validated. Unknown query parameters are ignored. Providing invalid filter values should yield a validation error.

# Welcome Implementing a new tool can be daunting, but it doesn't have to. You can implement journy.io in a few different ways to ensure it fits with the rest of your tech stack seamlessly. We welcome your feedback, ideas and suggestions. We really want to make your life easier, so if we’re falling short or should be doing something different, we want to hear about it. Send us an email at [hi@journy.io](mailto:hi@journy.io) or reach out via the chat on our website or on our platform. There are multiple ways you can send us data about users and accounts. We have both frontend and backend APIs, which can be used together at the same time. If you already use [Segment](https://segment.com/), you can [get up and running with journy.io in seconds](https://help.journy.io/en/articles/6488307-the-segment-connector). # Concepts ## Users The most basic entity is a user, a specific individual that completed an interaction with your product. We support multiple types of users, often differentiated by it's external ID prefix. E.g. In the case you are building an ordering app, there could easily be an administrator (who updates products and checks for orders) and the end-customers who place orders. One could have a typical ADM-XXXXXXXX ID, while the other would be referenced by USR-XXXXXXXXX. ## Accounts In B2B SaaS, users can be part of multiple accounts. E.g. Imagine you're building a content scheduling app where an agency can manage the social media posts of their clients. Each client of the agency has its own account in the product. If your app doesn't have the concept of a team or group of users, you can ignore accounts. ## Events An event is a data point that represents an interaction between a user and/or an account; and your product. Events can represents any range of interactions. E.g. Every time a customer creates an invoice in an invoicing app. Actions like creating an invoice can be tracked as an event in journy.io. It's critical to track events properly. You'll need to provide either an account ID, or a user ID, or both; when tracking an event. E.g. If a user updates his personal settings, you can omit the account ID as the event would not be related to any account. In a same logic, an account could get a 'suspend account' event (with account ID) from an internal process, whereas no user would be associated. In most cases, events will be associated to both 1 user and 1 account. You can optionally pass extra details as metadata (e.g. amount of the invoice). This gets particarly powerfull when creating computed properties on those event metadata. E.g. Our above ordering app could send journy.io 'Place Order' events with metadata 'price', on which journy.io very easily would compute a total order value (for each account) for the last 30 days. 💡 Metadata does not update the properties of a user or account. # Frontend vs backend The best implementations we see employ a hybrid approach to maximize data quality while maintaining the flexibility to easily collect the data they need. We recommend using our JavaScript snippet to track screen views and our backend API to sync users, sync accounts and track events. When evaluating how to track a particular event, we suggest starting with server-side and only use frontend if it's not possible to collect purely server-side. This can be the case if you need to track interactions with your product that don't result in any natural server requests (such as a button click that opens a modal). # Frontend ## Setup 💡 You can find the JavaScript snippet in the website settings in the connections view. Copy the JavaScript snippet and place it in the head or body of your application. The snippet automatically calls `journy("init", { ... })` and `journy("pageview")`. ## Identify user 💡 A user ID should be a robust, static, unique identifier that you recognize a user by in your own systems. Because these IDs are consistent across a customer’s lifetime, you should include a user ID in identify calls as often as you can. Ideally, the user ID should be a database ID. 💡 journy.io does not recommend using simple email addresses or usernames as user ID, as these can change over time. journy.io recommends that you use static IDs instead, so the IDs never change. When you use a static ID, you can still recognize the user in your analytics tools, even if the user changes their email address. 💡 The properties `full_name`, `first_name`, `last_name`, `phone` and `registered_at` will be used for creating contacts in destinations like Intercom, HubSpot, Salesforce, ... `journy("identify")` allows you to identify the user that is currently using your product. ```ts journy("identify", { // Email or user ID is required email: "john.doe@acme.com", // Unique identifier for the user in your database userId: "20", // Optional // Hash of the user ID using a backend secret // You can find the secret in the website settings // Recommended to prevent spoofing verification: "hash", // Optional properties: { full_name: "John Doe", // or first_name: "John", last_name: "Doe", phone: "123", registered_at: new Date(/* ... */), is_admin: true, key_with_empty_value: "", this_property_will_be_deleted: null, }, }); ``` ## Identify account 💡 An account ID should be a robust, static, unique identifier that you recognize an account by in your own systems. Ideally, the account ID should be a database ID. 💡 The properties `name`, `mrr`, `plan` and `registered_at` will be used to create companies in destinations like Intercom, HubSpot, Salesforce, ... `journy("account")` allows you to identify the business account (i.e. organization) using your product. ```ts journy("account", { // Required // Unique identifier for the account in your database accountId: "30", // Optional // Hash of the account ID using a backend secret // You can find the secret in the website settings // Recommended to prevent spoofing verification: "hash", // Optional properties: { name: "ACME, Inc", mrr: 399, plan: "Pro", registered_at: new Date(/* ... */), is_paying: true, key_with_empty_value: "", this_property_will_be_deleted: null, }, }); ``` ## Send page view 💡 In applications, we advise you to use screen views instead of page views. The JavaScript snippet in the site settings includes a `pageview` by default. ```ts journy("pageview"); ``` If you have a B2B application, we recommend to set account ID for every page view that happens within the context of an account. 💡 An account ID should be a robust, static, unique identifier that you recognize an account by in your own systems. Ideally, the account ID should be a database ID. ```ts journy("pageview", { accountId: "30", // Optional // Hash of the account ID using a backend secret // You can find the secret in the website settings // Recommended to prevent spoofing verification: "hash", }); ``` ## Send screen view In applications, we strongly advise you to use screen views instead of page views. Page URLs in applications often include the account ID (e.g. https://app.acme.com/accountId/settings). This makes it difficult to create signals, segments, ... based on those URLs. That's what screen views solve. It allows you to set a name for the screen being viewed (e.g. Account settings). ```ts journy("screen", { name: "Personal settings" }); ``` If you have a B2B application, we recommend to set account ID for every screen view that happens within the context of an account. Example: "Personal settings" would be without account ID, "Team settings" would be with account ID. 💡 An account ID should be a robust, static, unique identifier that you recognize an account by in your own systems. Ideally, the account ID should be a database ID. ```ts journy("screen", { name: "Account settings", accountId: "30", // Optional // Hash of the account ID using a backend secret // You can find the secret in the website settings // Recommended to prevent spoofing verification: "hash", }); ``` ## Trigger an event 💡 Use past tense for event names. User events: ```js journy("event", { // required name: "signed_in", // optional metadata: { key: "value", }, }); ``` Account events: 💡 An account ID should be a robust, static, unique identifier that you recognize an account by in your own systems. Ideally, the account ID should be a database ID. ```js journy("event", { // required name: "created_invoice", accountId: "30", // Optional // Hash of the account ID using a backend secret // You can find the secret in the website settings // Recommended to prevent spoofing verification: "hash", // optional metadata: { key: "value", amount: 100, allow_wire_transfer: true, }, }); ``` ## Identity verification Identity verification ensures that one person can't impersonate another. Identity verification requires you to add an hash (HMAC) (that you generate on your server using SHA256) to your installation snippet alongside your user ID and account ID. journy.io won't accept requests for a logged-in user without a valid hash. The hash is calculated using a secret key, which you should never share. Without this secret key, no third party can send journy.io a valid hash for one of your users, so they can't impersonate your users. This is optional but highly recommended. You can enable identify verification in the website settings in the connections view. ```js journy("identify", { userId: "userId", verification: "USER_ID_HMAC_VALUE_HERE" }) journy("account", { accountId: "accountId", verification: "ACCOUNT_ID_HMAC_VALUE_HERE" }) journy("event", { accountId: "accountId", verification: "ACCOUNT_ID_HMAC_VALUE_HERE" }) ``` ### PHP ```php { journy("screen", { name: "name" }); // or journy("pageview"); }, [location]); return ( // ... ); } ``` ### Vue Router You can use [`router.afterEach`](https://router.vuejs.org/guide/advanced/navigation-guards.html#global-after-hooks) to listen for route changes: ```js const router = new VueRouter({ ... }); router.afterEach((to, from) => { journy("screen", { name: "name" }); // or journy("pageview"); }); ``` Note: We don't accept a page URL argument for `journy("pageview")`. The current page URL will always be resolved using `window.location.href`. ## TypeScript We published an [npm package](https://www.npmjs.com/package/@journyio/web-types) with type definitions to enable type-safe usage of our JavaScript snippet. The code and documentation is available on [GitHub](https://github.com/journy-io/web-types). ## Localhost By default a site doesn't allow page views from other domains than the registered domain. This makes it difficult to test your tracking implementation locally. You can enable "Allow any domain" in the site settings to disable the domain check. This will allow you to test the JavaScript snippet with localhost as hostname. # Backend The journy.io API is organized around REST. Our API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. The API is hosted on api.journy.io. ## Official SDKs Our SDKs are designed to help you interact with our APIs with less friction. They are written in several different languages and help bridge the gap between your application and journy.io APIs. They take away the need to know the exact URL and HTTP method to use for each API call among other things leaving you more time to focus on making your application. | Language | Package | Source code | |------------|--------------------------------------------------------------------------------|----------------------------------------------------------------------------| | 💚 Node.js | [npm install @journyio/sdk ](https://www.npmjs.com/package/@journyio/sdk) | [github.com/journy-io/js-sdk](https://github.com/journy-io/js-sdk) | | 🐘 PHP | [composer require journy-io/sdk](https://packagist.org/packages/journy-io/sdk) | [github.com/journy-io/php-sdk](https://github.com/journy-io/php-sdk) | | 🐍 Python | [pip install journyio-sdk](https://pypi.org/project/journyio-sdk/) | [github.com/journy-io/python-sdk](https://github.com/journy-io/python-sdk) | | 💎 Ruby | Coming soon | Coming soon | Your favourite programming language not included? [Let us know!](mailto:hi@journy.io) In the meanwhile, you can use [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) to generate a client for your programming language. ## Authentication The journy.io API uses API keys to authenticate requests. You can view and manage your API keys in the [connections screen](https://system.journy.io). Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail. For every request send to the API we expect a header `X-Api-Key` to be set with the API Key. ## Permissions When creating an API Key in [the application](https://system.journy.io) you will have the choice to give permissions to an API Key (which you can change later on). These permissions restrict the API Key from different actions. When an API Key tries to perform a certain action it doesn't have the permissions for, you will receive a `401: Unauthorized` response. ## Rate limiting To prevent abuse of the API there is a maximum throughput of 1800 requests per minute. If you need a higher throughput, please contact us. To keep our platform healthy and stable, we'll block API keys that consistently hit our rate limits. Therefore, please consider taking this throughput into account. In every response the headers `X-RateLimit-Limit` and `X-RateLimit-Remaining` will be set. The `X-RateLimit-Limit`-header will always contain the current limit of requests per minute. The `X-RateLimit-Remaining`-header will always contain the amount of requests you have left in the current sliding window. 💡 The client-side tracking uses different rate limits. ## Errors journy.io uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g. a required parameter was omitted). Codes in the 5xx range indicate an error with journy.io's servers (these are rare). When performing a `POST`- or `PUT`-request with a requestBody, or when including parameters, these parameters and fields will automatically be checked and validated against the API Spec. When any error occurs, you will get a response with an `errors`-field, structured as follows: ```json { "errors": { "parameters": { "header": { "headerParameterName": "Describe what's wrong with the header parameter.", ... }, "query": { "queryParameterName": "Describe what's wrong with the query parameter.", ... }, "path": { "pathParameterName": "Describe what's wrong with the path parameter.", ... }, }, "fields": { "fieldName": "Describe what's wrong with the fieldName.", "object.fieldName": "Describe what's wrong with the fieldName of the included object.", ... } } } ``` ## Best practices ### Track accounts & users immediately on creation When you create an account in your database, immediately sending data about that account to journy.io helps your team stay in sync. The same goes for users. Call [Upsert account](#operation/upsertAccount) as soon as possible, right after the account is first created in your database. ### Update account data daily Not every account is active every day. But, you may have properties on the account that change through background processing. That's why we recommend updating every one of your accounts' data in a recurring daily process. This way, you know that your accounts are updated every day in journy.io. ## Changelog ### December 2021 [POST /events](#operation/trackJourneyEvent) will be moved to [POST /track](#operation/trackEvent). [POST /events](#operation/trackJourneyEvent) is deprecated and will be removed in the future.

## Introduction The Linode API provides the ability to programmatically manage the full range of Linode products and services. This reference is designed to assist application developers and system administrators. Each endpoint includes descriptions, request syntax, and examples using standard HTTP requests. Response data is returned in JSON format. This document was generated from our OpenAPI Specification. See the OpenAPI website for more information. Download the Linode OpenAPI Specification. ## Changelog View our Changelog to see release notes on all changes made to our API. ## Access and Authentication Some endpoints are publicly accessible without requiring authentication. All endpoints affecting your Account, however, require either a Personal Access Token or OAuth authentication (when using third-party applications). ### Personal Access Token The easiest way to access the API is with a Personal Access Token (PAT) generated from the Linode Cloud Manager or the [Create Personal Access Token](/docs/api/profile/#personal-access-token-create) endpoint. All scopes for the OAuth security model ([defined below](/docs/api/profile/#oauth)) apply to this security model as well. #### Authentication | Security Scheme Type: | HTTP | |-----------------------|------| | **HTTP Authorization Scheme** | bearer | ### OAuth If you only need to access the Linode API for personal use, we recommend that you create a [personal access token](/docs/api/#personal-access-token). If you're designing an application that can authenticate with an arbitrary Linode user, then you should use the OAuth 2.0 workflows presented in this section. For a more detailed example of an OAuth 2.0 implementation, see our guide on [How to Create an OAuth App with the Linode Python API Library](/docs/products/tools/api/guides/create-an-oauth-app-with-the-python-api-library/#oauth-2-authentication-exchange). Before you implement OAuth in your application, you first need to create an OAuth client. You can do this [with the Linode API](/docs/api/account/#oauth-client-create) or [via the Cloud Manager](https://cloud.linode.com/profile/clients): - When creating the client, you'll supply a `label` and a `redirect_uri` (referred to as the Callback URL in the Cloud Manager). - The response from this endpoint will give you a `client_id` and a `secret`. - Clients can be public or private, and are private by default. You can choose to make the client public when it is created. - A private client is used with applications which can securely store the client secret (that is, the secret returned to you when you first created the client). For example, an application running on a secured server that only the developer has access to would use a private OAuth client. This is also called a confidential client in some OAuth documentation. - A public client is used with applications where the client secret is not guaranteed to be secure. For example, a native app running on a user's computer may not be able to keep the client secret safe, as a user could potentially inspect the source of the application. So, native apps or apps that run in a user's browser should use a public client. - Public and private clients follow different workflows, as described below. #### OAuth Workflow The OAuth workflow is a series of exchanges between your third-party app and Linode. The workflow is used to authenticate a user before an application can start making API calls on the user's behalf. Notes: - With respect to the diagram in [section 1.2 of RFC 6749](https://tools.ietf.org/html/rfc6749#section-1.2), login.linode.com (referred to in this section as the *login server*) is the Resource Owner and the Authorization Server; api.linode.com (referred to here as the *api server*) is the Resource Server. - The OAuth spec refers to the private and public workflows listed below as the [authorization code flow](https://tools.ietf.org/html/rfc6749#section-1.3.1) and [implicit flow](https://tools.ietf.org/html/rfc6749#section-1.3.2). | PRIVATE WORKFLOW | PUBLIC WORKFLOW | |------------------|------------------| | 1. The user visits the application's website and is directed to login with Linode. | 1. The user visits the application's website and is directed to login with Linode. | | 2. Your application then redirects the user to Linode's [login server](https://login.linode.com) with the client application's `client_id` and requested OAuth `scope`, which should appear in the URL of the login page. | 2. Your application then redirects the user to Linode's [login server](https://login.linode.com) with the client application's `client_id` and requested OAuth `scope`, which should appear in the URL of the login page. | | 3. The user logs into the login server with their username and password. | 3. The user logs into the login server with their username and password. | | 4. The login server redirects the user to the specificed redirect URL with a temporary authorization `code` (exchange code) in the URL. | 4. The login server redirects the user back to your application with an OAuth `access_token` embedded in the redirect URL's hash. This is temporary and expires in two hours. No `refresh_token` is issued. Therefore, once the `access_token` expires, a new one will need to be issued by having the user log in again. | | 5. The application issues a POST request (*see additional details below*) to the login server with the exchange code, `client_id`, and the client application's `client_secret`. | | | 6. The login server responds to the client application with a new OAuth `access_token` and `refresh_token`. The `access_token` is set to expire in two hours. | | | 7. The `refresh_token` can be used by contacting the login server with the `client_id`, `client_secret`, `grant_type`, and `refresh_token` to get a new OAuth `access_token` and `refresh_token`. The new `access_token` is good for another two hours, and the new `refresh_token` can be used to extend the session again by this same method (*see additional details below*). | | #### OAuth Private Workflow - Additional Details The following information expands on steps 5 through 7 of the private workflow: Once the user has logged into Linode and you have received an exchange code, you will need to trade that exchange code for an `access_token` and `refresh_token`. You do this by making an HTTP POST request to the following address: ``` https://login.linode.com/oauth/token ``` Make this request as `application/x-www-form-urlencoded` or as `multipart/form-data` and include the following parameters in the POST body: | PARAMETER | DESCRIPTION | |-----------|-------------| | client_id | Your app's client ID. | | client_secret | Your app's client secret. | | code | The code you just received from the redirect. | You'll get a response like this: ```json { "scope": "linodes:read_write", "access_token": "03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c", "refresh_token": "f2ec9712e616fdb5a2a21aa0e88cfadea7502ebc62cf5bd758dbcd65e1803bad", "token_type": "bearer", "expires_in": 7200 } ``` Included in the response is an `access_token`. With this token, you can proceed to make authenticated HTTP requests to the API by adding this header to each request: ``` Authorization: Bearer 03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c ``` This `access_token` is set to expire in two hours. To refresh access prior to expiration, make another request to the same URL with the following parameters in the POST body: | PARAMETER | DESCRIPTION | |-----------|-------------| | grant_type | The grant type you're using. Use "refresh_token" when refreshing access. | | client_id | Your app's client ID. | | client_secret | Your app's client secret. | | refresh_token | The `refresh_token` received from the previous response. | You'll get another response with an updated `access_token` and `refresh_token`, which can then be used to refresh access again. #### OAuth Reference | Security Scheme Type | OAuth 2.0 | |-----------------------|--------| | **Authorization URL** | https://login.linode.com/oauth/authorize | | **Token URL** | https://login.linode.com/oauth/token | | **Scopes** |

• `account:read_only` - Allows access to GET information about your Account.
• `account:read_write` - Allows access to all endpoints related to your Account.
• `databases:read_only` - Allows access to GET Managed Databases on your Account.
• `databases:read_write` - Allows access to all endpoints related to your Managed Databases.
• `domains:read_only` - Allows access to GET Domains on your Account.
• `domains:read_write` - Allows access to all Domain endpoints.
• `events:read_only` - Allows access to GET your Events.
• `events:read_write` - Allows access to all endpoints related to your Events.
• `firewall:read_only` - Allows access to GET information about your Firewalls.
• `firewall:read_write` - Allows access to all Firewall endpoints.
• `images:read_only` - Allows access to GET your Images.
• `images:read_write` - Allows access to all endpoints related to your Images.
• `ips:read_only` - Allows access to GET your ips.
• `ips:read_write` - Allows access to all endpoints related to your ips.
• `linodes:read_only` - Allows access to GET Linodes on your Account.
• `linodes:read_write` - Allow access to all endpoints related to your Linodes.
• `lke:read_only` - Allows access to GET LKE Clusters on your Account.
• `lke:read_write` - Allows access to all endpoints related to LKE Clusters on your Account.
• `longview:read_only` - Allows access to GET your Longview Clients.
• `longview:read_write` - Allows access to all endpoints related to your Longview Clients.
• `nodebalancers:read_only` - Allows access to GET NodeBalancers on your Account.
• `nodebalancers:read_write` - Allows access to all NodeBalancer endpoints.
• `object_storage:read_only` - Allows access to GET information related to your Object Storage.
• `object_storage:read_write` - Allows access to all Object Storage endpoints.
• `stackscripts:read_only` - Allows access to GET your StackScripts.
• `stackscripts:read_write` - Allows access to all endpoints related to your StackScripts.
• `volumes:read_only` - Allows access to GET your Volumes.
• `volumes:read_write` - Allows access to all endpoints related to your Volumes.

| ## Requests Requests must be made over HTTPS to ensure transactions are encrypted. The following Request methods are supported: | METHOD | USAGE | |--------|-------| | GET | Retrieves data about collections and individual resources. | | POST | For collections, creates a new resource of that type. Also used to perform actions on action endpoints. | | PUT | Updates an existing resource. | | DELETE | Deletes a resource. This is a destructive action. | ## Responses Actions will return one following HTTP response status codes: | STATUS | DESCRIPTION | |---------|-------------| | 200 OK | The request was successful. | | 202 Accepted | The request was successful, but processing has not been completed. The response body includes a "warnings" array containing the details of incomplete processes. | | 204 No Content | The server successfully fulfilled the request and there is no additional content to send. | | 299 Deprecated | The request was successful, but involved a deprecated endpoint. The response body includes a "warnings" array containing warning messages. | | 400 Bad Request | You submitted an invalid request (missing parameters, etc.). | | 401 Unauthorized | You failed to authenticate for this resource. | | 403 Forbidden | You are authenticated, but don't have permission to do this. | | 404 Not Found | The resource you're requesting does not exist. | | 429 Too Many Requests | You've hit a rate limit. | | 500 Internal Server Error | Please [open a Support Ticket](/docs/api/support/#support-ticket-open). | ## Errors Success is indicated via Standard HTTP status codes. `2xx` codes indicate success, `4xx` codes indicate a request error, and `5xx` errors indicate a server error. A request error might be an invalid input, a required parameter being omitted, or a malformed request. A server error means something went wrong processing your request. If this occurs, please [open a Support Ticket](/docs/api/support/#support-ticket-open) and let us know. Though errors are logged and we work quickly to resolve issues, opening a ticket and providing us with reproducable steps and data is always helpful. The `errors` field is an array of the things that went wrong with your request. We will try to include as many of the problems in the response as possible, but it's conceivable that fixing these errors and resubmitting may result in new errors coming back once we are able to get further along in the process of handling your request. Within each error object, the `field` parameter will be included if the error pertains to a specific field in the JSON you've submitted. This will be omitted if there is no relevant field. The `reason` is a human-readable explanation of the error, and will always be included. ## Pagination Resource lists are always paginated. The response will look similar to this: ```json { "data": [ ... ], "page": 1, "pages": 3, "results": 300 } ``` * Pages start at 1. You may retrieve a specific page of results by adding `?page=x` to your URL (for example, `?page=4`). If the value of `page` exceeds `2^64/page_size`, the last possible page will be returned. * Page sizes default to 100, and can be set to return between 25 and 500. Page size can be set using `?page_size=x`. ## Filtering and Sorting Collections are searchable by fields they include, marked in the spec as `x-linode-filterable: true`. Filters are passed in the `X-Filter` header and are formatted as JSON objects. Here is a request call for Linode Types in our "standard" class: ```Shell curl "https://api.linode.com/v4/linode/types" \ -H 'X-Filter: { "class": "standard" }' ``` The filter object's keys are the keys of the object you're filtering, and the values are accepted values. You can add multiple filters by including more than one key. For example, filtering for "standard" Linode Types that offer one vcpu: ```Shell curl "https://api.linode.com/v4/linode/types" \ -H 'X-Filter: { "class": "standard", "vcpus": 1 }' ``` In the above example, both filters are combined with an "and" operation. However, if you wanted either Types with one vcpu or Types in our "standard" class, you can add an operator: ```Shell curl "https://api.linode.com/v4/linode/types" \ -H 'X-Filter: { "+or": [ { "vcpus": 1 }, { "class": "standard" } ] }' ``` Each filter in the `+or` array is its own filter object, and all conditions in it are combined with an "and" operation as they were in the previous example. Other operators are also available. Operators are keys of a Filter JSON object. Their value must be of the appropriate type, and they are evaluated as described below: | OPERATOR | TYPE | DESCRIPTION | |----------|--------|-----------------------------------| | +and | array | All conditions must be true. | | +or | array | One condition must be true. | | +gt | number | Value must be greater than number. | | +gte | number | Value must be greater than or equal to number. | | +lt | number | Value must be less than number. | | +lte | number | Value must be less than or equal to number. | | +contains | string | Given string must be in the value. | | +neq | string | Does not equal the value. | | +order_by | string | Attribute to order the results by - must be filterable. | | +order | string | Either "asc" or "desc". Defaults to "asc". Requires `+order_by`. | For example, filtering for [Linode Types](/docs/api/linode-types/) that offer memory equal to or higher than 61440: ```Shell curl "https://api.linode.com/v4/linode/types" \ -H ' X-Filter: { "memory": { "+gte": 61440 } }' ``` You can combine and nest operators to construct arbitrarily-complex queries. For example, give me all [Linode Types](/docs/api/linode-types/) which are either `standard` or `highmem` class, or have between 12 and 20 vcpus: ```Shell curl "https://api.linode.com/v4/linode/types" \ -H ' X-Filter: { "+or": [ { "+or": [ { "class": "standard" }, { "class": "highmem" } ] }, { "+and": [ { "vcpus": { "+gte": 12 } }, { "vcpus": { "+lte": 20 } } ] } ] }' ``` ## Time Values All times returned by the API are in UTC, regardless of the timezone configured within your user's profile (see `timezone` property within [Profile View](/docs/api/profile/#profile-view__responses)). ## Rate Limiting Rate limits on API requests help maintain the health and stability of the Linode API. Accordingly, every endpoint of the Linode API applies a rate limit on a per user basis as determined by OAuth token for authenticated requests or IP address for public endpoints. Each rate limit consists of a total number of requests and a time window. For example, if an endpoint has a rate limit of 800 requests per minute, then up to 800 requests over a one minute window are permitted. Subsequent requests to an endpoint after hitting a rate limit return a 429 error. You can successfully remake requests to that endpoint after the rate limit window resets. ### Linode APIv4 Rate Limits With the Linode API, you can generally make up to 1,600 general API requests every two minutes. Additionally, all endpoints have a rate limit of 800 requests per minute unless otherwise specified below. **Note:** There may be rate limiting applied at other levels outside of the API, for example, at the load balancer. Creating Linodes has a dedicated rate limit of 10 requests per 30 seconds. That endpoint is: * [Linode Create](/docs/api/linode-instances/#linode-create) `/stats` endpoints have their own dedicated rate limits of 100 requests per minute. These endpoints are: * [View Linode Statistics](/docs/api/linode-instances/#linode-statistics-view) * [View Linode Statistics (year/month)](/docs/api/linode-instances/#statistics-yearmonth-view) * [View NodeBalancer Statistics](/docs/api/nodebalancers/#nodebalancer-statistics-view) * [List Managed Stats](/docs/api/managed/#managed-stats-list) Object Storage endpoints have a dedicated rate limit of 750 requests per second. The Object Storage endpoints are: * [Object Storage Endpoints](/docs/api/object-storage/) Opening Support Tickets has a dedicated rate limit of 2 requests per minute. That endpoint is: * [Open Support Ticket](/docs/api/support/#support-ticket-open) Accepting Service Transfers has a dedicated rate limit of 2 requests per minute. That endpoint is: * [Service Transfer Accept](/docs/api/account/#service-transfer-accept) ### Rate Limit HTTP Response Headers The Linode API includes the following HTTP response headers which are designed to help you avoid hitting rate limits that might disrupt your applications: * **X-RateLimit-Limit**: The maximum number of permitted requests during the rate limit window for this endpoint. * **X-RateLimit-Remaining**: The remaining number of permitted requests in the current rate limit window. * **X-RateLimit-Reset**: The time when the current rate limit window rests in UTC epoch seconds. * **Retry-After**: The remaining time in seconds until the current rate limit window resets. There are many ways to access header information for your requests, depending on how you are accessing the Linode API. For example, to view HTTP response headers when making requests with `curl`, use the `-i` or `--include` option as follows: ```Shell curl -i https://api.linode.com/v4/regions ``` ## CLI (Command Line Interface) The Linode CLI allows you to easily work with the API using intuitive and simple syntax. It requires a [Personal Access Token](/docs/api/#personal-access-token) for authentication, and gives you access to all of the features and functionality of the Linode API that are documented here with CLI examples. Endpoints that do not have CLI examples are currently unavailable through the CLI, but can be accessed via other methods such as Shell commands and other third-party applications.

the purpose of this application is to provide an application that is using plain go code to define an API This should demonstrate all the possible comment annotations that are available to turn go code into a fully compliant swagger 2.0 spec

Autosuggest supplies search terms derived from a root text sent to the service. The terms Autosuggest supplies are related to the root text based on similarity and their frequency or ratings of usefulness in other searches. For examples that show how to use Autosuggest, see [Search using AutoSuggest](https://docs.microsoft.com/en-us/rest/api/cognitiveservices/bing-autosuggest-api-v7-reference).

The Computer Vision API provides state-of-the-art algorithms to process images and return information. For example, it can be used to determine if an image contains mature content, or it can be used to find all the faces in an image. It also has other features like estimating dominant and accent colors, categorizing the content of images, and describing an image with complete English sentences. Additionally, it can also intelligently generate images thumbnails for displaying large images effectively.

The Bing Custom Image Search API lets you send an image search query to Bing and get back image search results customized to meet your custom search definition.

The Bing Custom Search API lets you send a search query to Bing and get back search results customized to meet your custom search definition.

The Entity Search API lets you send a search query to Bing and get back search results that include entities and places. Place results include restaurants, hotel, or other local businesses. For places, the query can specify the name of the local business or it can ask for a list (for example, restaurants near me). Entity results include persons, places, or things. Place in this context is tourist attractions, states, countries, etc.

The Image Search API lets you send a search query to Bing and get back a list of relevant images. This section provides technical details about the query parameters and headers that you use to request images and the JSON response objects that contain them. For examples that show how to make requests, see [Searching the Web for Images](https://docs.microsoft.com/azure/cognitive-services/bing-image-search/search-the-web).

The Local Search client lets you send a search query to Bing and get back search results that include local businesses such as restaurants, hotels, retail stores, or other local businesses. The query can specify the name of the local business or it can ask for a list (for example, restaurants near me).

The News Search API lets you send a search query to Bing and get back a list of news that are relevant to the search query. This section provides technical details about the query parameters and headers that you use to request news and the JSON response objects that contain them. For examples that show how to make requests, see [Searching the web for news](https://docs.microsoft.com/en-us/azure/cognitive-services/bing-news-search/search-the-web).

The Computer Vision API provides state-of-the-art algorithms to process images and return information. For example, it can be used to determine if an image contains mature content, or it can be used to find all the faces in an image. It also has other features like estimating dominant and accent colors, categorizing the content of images, and describing an image with complete English sentences. Additionally, it can also intelligently generate images thumbnails for displaying large images effectively.