{ "openapi": "3.0.1", "info": { "title": "Log Analysis API", "description": "*REST API to send log data, export data and manage configuration*\n\nTo utilize the inline testing functionality here, please go into your Mezmo account and add the following\naddress to your CORS Origins page: `https://docs.mezmo.com`.\n", "version": "2.1" }, "servers": [ { "url": "https://api.mezmo.com" } ], "security": [ { "AccessToken": [] } ], "tags": [ { "name": "Archiving", "description": ">*Authentication*: You can find instructions on authentication [here](/log-analysis-api/ref#authentication).\n\nThe LogDNA Archiving API enables you to programmatically configure your archiving instances via code.\nSpecifically you can set up cold storage buckets to send your logs for long term storage.\n" }, { "name": "Board", "description": ">*Authentication*: You can find instructions on authentication [here](/log-analysis-api/ref#authentication).\n\nThe LogDNA's API's Board endpoints are used to create, get, list, and delete boards.\n" }, { "name": "Configuration", "description": ">*Authentication*: You can find instructions on authentication [here](/log-analysis-api/ref#authentication).\n\nThe LogDNA API's Configuration endpoints are used to create, update, and delete views, alerts, and categories.\n" }, { "name": "Export", "description": "LogDNA provides two endpoints for exporting your log lines.\nRead the sections below to learn about each, and determine which is appropriate for your use case.\n\n## Export API v1\nThe Export API v1 is used to export log lines in [JSONL](https://jsonlines.org/) format. Based on\nyour specific plan, the maximum number of logs returned is limited to 10,000 / 20,000. There are two distinct functionalities:\n1. Streaming desired log lines directly from the response as raw text data\n2. Specifying an email to receive a link that can be used to the download the desired log lines\n\n> Note\n> When an email address is specified, the desired log lines will not be streamed to the response body.\n> The response will instead send a notification indicating that the request was successful and that the results\n> will be sent to the email address provided in the request. This entails archiving and uploading the desired logs\n> to a storage provider. The email includes a URI to download the logs. Be aware that access to this URI will expire\n> after 24-48 hours.\n\n## Export API v2\nThe Export API v2 provides an enhancement over v1, allowing you to export any number of log lines using pagination and\nby-passing the plan-specific limit imposed in v1. By making (multiple) subsequent requests using the `pagination_id` parameter,\nyou can retrieve logs in batches of JSON until all matching log lines have been returned.\n\nEach Export API v2 request is limited to 10,000 lines.\n\n### Pagination Functionality\nPagination is only necessary when the desired set of log lines is larger than 10,000, since this is the maximum number of results\nthat can be returned in a given page. If an export does not exceed this size, the behavior is similar to v1 -- all of the logs will be\nreturned in a single \"page\" and no further requests are needed. When an export does exceed this size, refer to the steps outlined below.\n\nThis is the expected workflow to export a set (cardinality > 10,000) of log lines that requires pagination:\n1. Send an initial request with valid query parameters to retrieve logs. Pass a `null` value for the `pagination_id` in the first request.\n2. The JSON response contains 2 fields: `lines` and `pagination_id`. The former is an array containing the corresponding batch (the first\n batch in this case) of logs and the latter is a token used to retrieve the next page of results.\n3. Send a subsequent request using the same initial query parameters and also passing in the token received in the response to the `pagination_id`\n parameter. This will retrieve the next page of results.\n4. Repeat this request-response cycle, updating the `pagination_id` parameter with the token returned in every new response, until the\n response eventually returns a `null` value for the token. This indicates that the corresponding batch of logs is the last and that you have\n reached the final page.\n\n> Important Considerations\n> In subsequent requests to paginate through results, make sure none of the query parameters & values are modified from the initial request\n> (excluding `pagination_id`)\n\n> The tokens used in the `pagination_id` parameter are tied to a specific export and page so they can be used repeatedly in requests to return\n> deterministic results\n\n> \"0\" can be passed in to the `from` and `to` parameters which will be resolved to timestamps for a plan's retention boundary and the current\n> time respectively. This behavior is independent so the value can be passed interchangeably to the parameters -- resulting in 4 possible scenarios:\n> - [`from`: \\, `to`: \\]\n> - [`from`: 0 (retention boundary), `to`: \\]\n> - [`from`: \\, `to`: 0 (current time)]\n> - [`from`: 0 (retention boundary), `to`: 0 (current time)]\n" }, { "name": "Ingestion", "description": "Ingestion API" }, { "name": "Exclusions", "description": ">*Authentication*: You can find instructions on authentication [here](/log-analysis-api/ref#authentication).\n\nControl what you store by creating exclusion rules. New lines that match an exclusion rule will not be stored and will not count toward your storage quota.\n" }, { "name": "Suspensions", "description": ">*Authentication*: You can find instructions on authentication [here](/log-analysis-api/ref#authentication).\n\nThe LogDNA Start/Stop Ingestion API allows users to programmatically manage their data ingestion status.\n\nUsers can get the current status of their ingestion, suspend their ingestion, and resume their ingestion. To prevent an\naccidental API call, the suspension of ingestion requires two subsequent API calls.\n\n> You can find instructions on authentication [here](/log-analysis-api/ref#authentication).\n" }, { "name": "Usage v1", "description": ">*Authentication*: You can find instructions on authentication [here](/log-analysis-api/ref#authentication).\n\nThe Usage API provides endpoints for retrieving aggregated usage information for applications, hosts and tags during a time period.\n\nWhile the `to` and `from` times are unix timestamps, the report is granular by day. Therefore only the day portion is used to establish a date range.\n\n### How is **Usage** defined?\n\nThis API defines usage as a percentage of the total number of lines ingested by the account within the defined period of time. For\nexample, an app called `myapp` that returns a percentage of `15` in the response object has 15 percent of their logs coming from `myapp`.\n" }, { "name": "Usage v2", "description": ">*Authentication*: You can find instructions on authentication [here](/log-analysis-api/ref#authentication).\n\nThe Usage API provides endpoints for retrieving aggregated usage information for applications, hosts and tags during a time period.\n\nWhile the `to` and `from` times are unix timestamps, the report is granular by day. Therefore only the day portion is used to establish a date range.\n\n### How is **Usage** defined?\n\nThis API defines usage as the number of bytes used by the log lines stored\non disk by the account within the defined period of time. For example,\nan app called `myapp` that returns `150,000` total bytes in the response\nobject indicates that `myapp` is consuming `150,000` bytes of disk storage\nover the time range.\n" } ], "paths": { "/logs/ingest": { "servers": [ { "url": "https://logs.mezmo.com" } ], "post": { "security": [ { "apikeyAuth": [] }, { "basicAuth": [] } ], "tags": [ "Ingestion" ], "summary": "Send Log Lines", "description": "Use this method to send logs to a logging instance.\n\n### Authentication\nYou can find instructions on authentication [here](/log-analysis-api/ref#authentication). Ingestion is\nsimilar to the other APIs, but instead of `servicekey` you will use `apikey` if\nyou are using the header style authentication.\n\n### Metadata\nMeta is a field reserved for custom information associated with a log line. To add \nmetadata to an API call, specify the `meta` field under the lines object. Metadata can be\nviewed inside that line's context\n\nWARNING: If inconsistent value types are\nused, that line's metadata, will not be parsed. For example, if a line is passed\nwith a meta object, such as `meta.myfield` of type String, any subsequent lines\nwith `meta.myfield` must have a String as the value type for `meta.myfield`.\n> Please be aware of [service limits](https://docs.mezmo.com/docs/Mezmo-ingestion-service-limits)\n> on this endpoint\n", "operationId": "ingest", "parameters": [ { "name": "hostname", "in": "query", "description": "Host name of the source.", "required": true, "schema": { "type": "string" } }, { "name": "mac", "in": "query", "description": "The network mac address of the host computer.", "schema": { "$ref": "#/components/schemas/mac" } }, { "name": "ip", "in": "query", "description": "The local IP address of the host computer.", "schema": { "$ref": "#/components/schemas/ip" } }, { "name": "now", "in": "query", "description": "The source UNIX timestamp in milliseconds at the time of the request. Used to calculate time drift.", "schema": { "type": "string" } }, { "name": "tags", "in": "query", "description": "Tags that are used to dynamically group hosts.", "schema": { "type": "string" } } ], "requestBody": { "description": "You can send multiple log lines in a request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ingestlines" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "401": { "description": "Unauthorized", "content": {} }, "403": { "description": "Forbidden", "content": {} }, "404": { "description": "Not Found", "content": {} } }, "deprecated": false, "x-codegen-request-body-name": "ingestlines" } }, "/v1/export": { "get": { "tags": [ "Export" ], "summary": "Export log lines", "description": "Use this method to export logs in JSON format from a logging instance.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `log` | `read` | Lets you pull your log lines back out of Mezmo in bulk |", "operationId": "export", "parameters": [ { "name": "from", "in": "query", "description": "Start time. Set as UNIX timestamp in seconds or milliseconds.", "required": true, "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "End time. Set as UNIX timestamp in seconds or milliseconds.", "required": true, "schema": { "type": "string" } }, { "name": "size", "in": "query", "description": "Number of log lines to include in the export.", "schema": { "type": "string" } }, { "name": "hosts", "in": "query", "description": "Comma-separated list of hosts.", "schema": { "type": "string" } }, { "name": "apps", "in": "query", "description": "Comma-separated list of applications.", "schema": { "type": "string" } }, { "name": "levels", "in": "query", "description": "Comma-separated list of log levels.", "schema": { "type": "string" } }, { "name": "query", "in": "query", "description": "Search query.", "schema": { "type": "string" } }, { "name": "prefer", "in": "query", "description": "Defines the log lines that you want to export. Valid values are head, first log lines, and tail, last log lines. If not specified, defaults to tail.", "schema": { "type": "string" } }, { "name": "email", "in": "query", "description": "Specifies the email with the downloadable link of your export. By default, the log lines are streamed.", "schema": { "type": "string" } }, { "name": "emailSubject", "in": "query", "description": "Use to set the subject of the email. Use to represent a space. For example, a sample value is Export logs.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } }, "deprecated": false } }, "/v2/export": { "get": { "tags": [ "Export" ], "summary": "Export log lines", "description": "Use this method to export logs in JSON format from a logging instance.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `log` | `read` | Lets you pull your log lines back out of Mezmo in bulk |", "operationId": "exportv2", "parameters": [ { "name": "from", "in": "query", "description": "Start time (inclusive). Set as UNIX timestamp in seconds or milliseconds.", "required": true, "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "End time (inclusive). Set as UNIX timestamp in seconds or milliseconds.", "required": true, "schema": { "type": "string" } }, { "name": "size", "in": "query", "description": "Number of log lines to include in the export.", "schema": { "type": "string" } }, { "name": "hosts", "in": "query", "description": "Comma-separated list of hosts.", "schema": { "type": "string" } }, { "name": "apps", "in": "query", "description": "Comma-separated list of applications.", "schema": { "type": "string" } }, { "name": "levels", "in": "query", "description": "Comma-separated list of log levels.", "schema": { "type": "string" } }, { "name": "query", "in": "query", "description": "Search query.", "schema": { "type": "string" } }, { "name": "prefer", "in": "query", "description": "Defines the log lines that you want to export. Valid values are head, first log lines, and tail, last log lines. If not specified, defaults to tail.", "schema": { "type": "string" } }, { "name": "pagination_id", "in": "query", "description": "ID that indicates which page of results to be retrieved. Leave empty for the initial export request.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } }, "deprecated": false } }, "/v1/config/view": { "get": { "tags": [ "Configuration" ], "summary": "List Views", "description": "Get a list of views.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `view` | `read` | Lets you see what views your team has saved |", "operationId": "list-view", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } } }, "post": { "tags": [ "Configuration" ], "summary": "Create View", "description": "Use this method to create a view and attach alerts to the view.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `view` | `write` | Lets you save a new view and hang alerts off it |", "operationId": "create-view", "requestBody": { "description": "Request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/configRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } }, "deprecated": false, "x-codegen-request-body-name": "configRequest" } }, "/v1/config/view/{viewId}": { "get": { "tags": [ "Configuration" ], "summary": "Get View", "description": "Gets the configuration for a specific view.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `view` | `read` | Lets you open a view and see its query and whatever alerts are attached |", "operationId": "get-view", "parameters": [ { "name": "viewId", "in": "path", "description": "ID of a view.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } } }, "put": { "tags": [ "Configuration" ], "summary": "Update View", "description": "Use this method to update a view. You can change the view configuration details; add or remove\nview specific alerts; or attach and detach preset alerts.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `view` | `write` | Lets you retune a view's query, or change which alerts are attached to it |", "operationId": "update-view", "parameters": [ { "name": "viewId", "in": "path", "description": "ID of a view.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/configRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } }, "deprecated": false, "x-codegen-request-body-name": "configRequest" }, "delete": { "tags": [ "Configuration" ], "summary": "Delete View", "description": "Use this method to delete a view and any attached alerts.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `view` | `manage` | Lets you delete a view, taking its attached alerts down with it |", "operationId": "delete-view", "parameters": [ { "name": "viewId", "in": "path", "description": "ID of a view.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } }, "deprecated": false, "x-codegen-request-body-name": "configRequest" } }, "/v1/config/groups": { "get": { "tags": [ "Groups" ], "summary": "List Groups", "description": "Use this method to list the log groups.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `role` | `read` | Lets you see what log groups have been set up on the account |", "operationId": "list-group", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } }, "deprecated": false }, "post": { "tags": [ "Groups" ], "summary": "Create Group", "description": "Use this method to create a log group where you can scope the data that is accessible by members\nin that group.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `role` | `write` | Lets you carve out a new group and decide what data its members can reach |", "operationId": "create-group", "parameters": [ { "name": "servicekey", "in": "header", "description": "A provisioned service key for your account.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/groupsRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } }, "deprecated": false, "x-codegen-request-body-name": "groupsRequest" } }, "/v1/config/groups/{groupId}": { "get": { "tags": [ "Groups" ], "summary": "Get Group", "description": "Use this method to get information on a group.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `role` | `read` | Lets you check exactly what data a group's members can reach |", "operationId": "read-group", "parameters": [ { "name": "groupId", "in": "path", "description": "ID of a group.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } }, "deprecated": false }, "delete": { "tags": [ "Groups" ], "summary": "Delete Group", "description": "Use this method to list the log groups.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `role` | `manage` | Lets you delete a group, revoking its data access from everyone assigned to it |", "operationId": "delete-group", "parameters": [ { "name": "servicekey", "in": "header", "description": "A provisioned service key for your account.", "required": true, "schema": { "type": "string" } }, { "name": "groupId", "in": "path", "description": "ID of a group.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } }, "deprecated": false }, "patch": { "tags": [ "Groups" ], "summary": "Update Group", "description": "Use this method to modify a log group. You can change the name of the group and the access scope\nthat defines the data that is accessible by members in that group.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `role` | `write` | Lets you rename a group, or widen and narrow what its members can reach |", "operationId": "update-group", "parameters": [ { "name": "servicekey", "in": "header", "description": "A provisioned service key for your account.", "required": true, "schema": { "type": "string" } }, { "name": "groupId", "in": "path", "description": "ID of a group.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/groupsRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } }, "deprecated": false, "x-codegen-request-body-name": "groupsRequest" } }, "/v1/config/archiving": { "get": { "tags": [ "Archiving" ], "summary": "Get Archive Configuration", "description": "Use this method to get an existing archiving configuration.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `archiving` | `read` | Lets you see where your logs are being archived and how they get there |", "operationId": "get-v1-config-archiving", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/archivingConfigRequest" } } } }, "404": { "description": "Archiving configuration not found", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/errPropsDefault" } } } } } }, "post": { "tags": [ "Archiving" ], "summary": "Create Archive Configuration", "description": "Use this method to configure archiving for an instance. Only one archiving configuration may\nexist at any time.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `archiving` | `write` | Lets you switch archiving on and point it at your own storage bucket |", "operationId": "post-v1-config-archiving", "requestBody": { "description": "Request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/archivingConfigRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/archivingConfigRequest" } } } }, "400": { "description": "Bad request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/errPropsDefault" } } } }, "409": { "description": "An archiving configuration already exists. Cannot create a new one", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/errPropsDefault" } } } } }, "deprecated": false, "x-codegen-request-body-name": "configRequest" }, "put": { "tags": [ "Archiving" ], "summary": "Update Archive Configuration", "description": "Use this method to update an existing archiving configuration.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `archiving` | `write` | Lets you move archiving to a different bucket, or refresh its credentials |", "operationId": "put-v1-config-archiving", "requestBody": { "description": "Request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/archivingConfigRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/archivingConfigRequest" } } } }, "400": { "description": "Bad request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/errPropsDefault" } } } }, "404": { "description": "Existing archiving integration not found", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/errPropsDefault" } } } } }, "deprecated": false, "x-codegen-request-body-name": "configRequest" }, "delete": { "tags": [ "Archiving" ], "summary": "Delete Archive Configuration", "description": "Use this method to delete the archiving configuration.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `archiving` | `manage` | Lets you switch archiving off and clear out the destination settings |", "operationId": "delete-v1-config-archiving", "responses": { "200": { "description": "OK", "content": {} }, "404": { "description": "Archiving configuration not found", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/errPropsDefault" } } } } } } }, "/v1/config/board": { "get": { "tags": [ "Board" ], "summary": "List Boards", "description": "Get a list of boards.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `board` | `read` | Lets you see what boards your team has built |", "operationId": "list-board", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "boardid": { "type": "string", "example": "0000000000" }, "account": { "$ref": "#/components/schemas/accountId" }, "title": { "type": "string", "description": "Name of the board" } } } } } } }, "400": { "description": "Bad request", "content": {} } } }, "post": { "tags": [ "Board" ], "summary": "Create Board", "description": "Use this method to create a board.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `board` | `write` | Lets you put together a new board of your own |", "operationId": "create-board", "requestBody": { "description": "Request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/boardRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } }, "deprecated": false, "x-codegen-request-body-name": "configRequest" } }, "/v1/config/board/{boardId}": { "get": { "tags": [ "Board" ], "summary": "Get Board", "description": "Gets the configuration for a specific board.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `board` | `read` | Lets you open a board and look at the graphs on it |", "operationId": "get-board", "parameters": [ { "name": "boardId", "in": "path", "description": "ID of a board.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "boardid": { "type": "string", "example": "0000000000" }, "account": { "$ref": "#/components/schemas/accountId" }, "title": { "type": "string", "description": "Name of the board" }, "graphs": { "type": "array", "items": { "type": "object" } }, "order": { "type": "array", "items": { "type": "string" } }, "category": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Bad request", "content": {} } } }, "delete": { "tags": [ "Board" ], "summary": "Delete Board", "description": "Use this method to delete a board.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `board` | `manage` | Lets you delete a board, which removes it for everyone on the account |", "operationId": "delete-board", "parameters": [ { "name": "boardId", "in": "path", "description": "ID of a board.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } }, "deprecated": false, "x-codegen-request-body-name": "boardRequest" } }, "/v1/config/ingestion/exclusions": { "get": { "tags": [ "Exclusions" ], "summary": "List Exclusion Rules", "description": "Returns a list of exclusion rules. Note: This does not return usage quota rules.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `exclusion` | `read` | Lets you see what's being dropped before it ever gets indexed |", "operationId": "get-v1-config-exclusions", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/streamExclusionRequest" } } } } }, "500": { "description": "Internal Server error occured when trying to fetch exclusion rules", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/errPropsDefault" } } } } } }, "post": { "tags": [ "Exclusions" ], "summary": "Create Exclusion Rule", "description": "Create a new ingestion exclusion rule to help reduce log volume\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `exclusion` | `write` | Lets you stop noisy lines being indexed, and counting toward your bill |", "operationId": "post-v1-config-exclusions", "requestBody": { "description": "Request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/streamExclusionRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/streamExclusionRequest" } } } }, "400": { "description": "Bad request. Query inside of exclusion rule failed to parse.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/errPropsDefault" } } } }, "500": { "description": "An internal error occured when trying to create exclusion rule.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/errPropsDefault" } } } } } } }, "/v1/config/ingestion/exclusions/{id}": { "get": { "tags": [ "Exclusions" ], "summary": "Get Exclusion Rule", "description": "Returns an exclusion rule with the id specified.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `exclusion` | `read` | Lets you check exactly what a single rule is matching on |", "operationId": "get-v1-config-exclusions-single", "parameters": [ { "name": "id", "in": "path", "description": "ID of an exclusion rule.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/streamExclusionRequest" } } } } }, "400": { "description": "Malformed ingestion exclusion rule response payload. The exclusion rule may be stored incorrectly", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/errPropsDefault" } } } }, "404": { "description": "Exclusion rule not found", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/errPropsDefault" } } } }, "500": { "description": "Internal Server Error. Failed to get exclusion rule", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/errPropsDefault" } } } } } }, "patch": { "tags": [ "Exclusions" ], "summary": "Update Exclusion Rule", "description": "Updates an existing exclusion rule\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `exclusion` | `write` | Lets you adjust what a rule drops when it's catching too much or too little |", "operationId": "patch-v1-config-exclusions-single", "parameters": [ { "name": "id", "in": "path", "description": "ID of an exclusion rule.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/streamExclusionRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/streamExclusionRequest" } } } }, "400": { "description": "Bad request. The rule is invalid. Double check rule and query syntax and try again.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/errPropsDefault" } } } }, "500": { "description": "Internal server error. The rule could not be updated at this time.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/errPropsDefault" } } } } } }, "delete": { "tags": [ "Exclusions" ], "summary": "Delete Exclusion Rule", "description": "Use this method to delete an exclusion rule.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `exclusion` | `manage` | Lets you delete a rule, so the lines it was filtering get indexed again |", "operationId": "delete-v1-config-exclusions-single", "parameters": [ { "name": "id", "in": "path", "description": "ID of an exclusion rule.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": {} }, "404": { "description": "Exclusion rule not found", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/errPropsDefault" } } } }, "500": { "description": "Internal Server Error. Failed to delete exclusion rule.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/errPropsDefault" } } } } } } }, "/v1/config/ingestion/status": { "get": { "tags": [ "Suspensions" ], "summary": "Get Ingestion Status", "description": "Retrieve the status of ingestion\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `log` | `read` | Lets you check whether your account is still taking in log data |", "operationId": "get-v1-config-ingestion-status", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "isIngesting": { "type": "boolean" } } } } } }, "500": { "description": "Failed to fetch ingestion status" } } } }, "/v1/config/ingestion/suspend": { "post": { "tags": [ "Suspensions" ], "summary": "Initiate Ingestion Suspension", "description": "First step in suspending ingestion for the instance. Returns a token for use in /suspend/confirm\nto actually stop ingestion\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `log` | `manage` | Lets you start the process of pausing ingestion for the whole account |", "operationId": "post-v1-config-ingestion-suspend", "responses": { "200": { "description": "Token to be used in /suspend/confirm", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "$ref": "#/components/schemas/uuid4" } } } } } } } } }, "/v1/config/ingestion/suspend/confirm": { "post": { "tags": [ "Suspensions" ], "summary": "Confirm Ingestion Suspension", "description": "After /suspend is called, a token is returned for use with this route as a confirmation.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `log` | `manage` | Actually stops ingestion \u2014 anything sent while you're suspended is gone for good |", "operationId": "post-v1-config-ingestion-suspend-confirm", "requestBody": { "description": "Request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "$ref": "#/components/schemas/uuid4" } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/standardResponse200" }, "400": { "description": "Bad Suspend Token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errPropsDefault" } } } }, "500": { "description": "Failed to fetch ingestion status" } } } }, "/v1/config/ingestion/resume": { "post": { "tags": [ "Suspensions" ], "summary": "Resume Ingestion", "description": "Resumes ingestion if it has been previously suspended\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `log` | `manage` | Lets you start taking log data in again after a suspension |", "operationId": "post-v1-config-ingestion-resume", "responses": { "200": { "$ref": "#/components/responses/standardResponse200" }, "500": { "description": "Failed to fetch ingestion status" } } } }, "/v1/config/presetalert": { "get": { "tags": [ "Configuration" ], "summary": "List Preset Alerts", "description": "Returns all Preset Alerts in the account.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `alert` | `read` | Lets you see what preset alerts you can hang off your views |", "operationId": "list-alerts", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } } }, "post": { "tags": [ "Configuration" ], "summary": "Create Preset Alert", "description": "Use this method to create a preset alert.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `alert` | `write` | Lets you set up a reusable alert that any view can share |", "operationId": "create-alert", "requestBody": { "description": "Request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/presetRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } } } }, "/v1/config/presetalert/{presetId}": { "get": { "tags": [ "Configuration" ], "summary": "Get Preset Alert", "description": "Get a specific preset alert\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `alert` | `read` | Lets you check what a preset alert fires on and where it sends notifications |", "operationId": "get-alert", "parameters": [ { "name": "presetId", "in": "path", "description": "ID of a preset alert.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } } }, "put": { "tags": [ "Configuration" ], "summary": "Update Alert", "description": "Update a specific preset alert.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `alert` | `write` | Lets you retune when an alert fires, or send its notifications somewhere else |", "operationId": "update-preset", "parameters": [ { "name": "presetId", "in": "path", "description": "ID of a preset alert.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/presetRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } } }, "delete": { "tags": [ "Configuration" ], "summary": "Delete Alert", "description": "Use this method to delete a preset alert.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `alert` | `manage` | Lets you delete a preset alert, unhooking it from every view using it |", "operationId": "delete-alert", "parameters": [ { "name": "presetId", "in": "path", "description": "ID of a preset alert.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } } } }, "/v1/usage/apps": { "get": { "tags": [ "Usage v1" ], "summary": "List Usage By App", "description": "Lists aggregated usage information for all apps during a time period.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `log` | `read` | Lets you see which apps are using the most of your log volume |", "operationId": "list-usage-app", "parameters": [ { "name": "from", "in": "query", "description": "Start date. Set as UNIX timestamp in seconds.", "required": true, "schema": { "type": "integer" } }, { "name": "to", "in": "query", "description": "End date. Set as UNIX timestamp in seconds.", "required": true, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "description": "Maximum amount of apps to retrieve.", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } } } }, "/v1/usage/apps/{name}": { "get": { "tags": [ "Usage v1" ], "summary": "Get Usage By App", "description": "Gets the aggregated usage information for an app matching the name provided as a path parameter,\nduring a time period. Returns null when not found.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `log` | `read` | Lets you check how much log volume a single app is using |", "operationId": "get-usage-app", "parameters": [ { "name": "name", "in": "path", "description": "The name of the app from which to get the aggregated usage data", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Start date. Set as UNIX timestamp in seconds.", "required": true, "schema": { "type": "integer" } }, { "name": "to", "in": "query", "description": "End date. Set as UNIX timestamp in seconds.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } } } }, "/v1/usage/tags": { "get": { "tags": [ "Usage v1" ], "summary": "List Usage by Tag", "description": "Lists aggregated usage information for all tags during a time period.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `log` | `read` | Lets you see which tags are using the most of your log volume |", "operationId": "list-usage-tag", "parameters": [ { "name": "from", "in": "query", "description": "Start date. Set as UNIX timestamp in seconds.", "required": true, "schema": { "type": "integer" } }, { "name": "to", "in": "query", "description": "End date. Set as UNIX timestamp in seconds.", "required": true, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "description": "Maximum amount of apps to retrieve.", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } } } }, "/v1/usage/tags/{name}": { "get": { "tags": [ "Usage v1" ], "summary": "Get Usage by Tag", "description": "Gets the aggregated usage information for a tag matching the name provided as a path parameter,\nduring a time period. Returns null when not found.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `log` | `read` | Lets you check how much log volume a single tag is using |", "operationId": "get-usage-tag", "parameters": [ { "name": "name", "in": "path", "description": "The name of the app from which to get the aggregated usage data", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Start date. Set as UNIX timestamp in seconds.", "required": true, "schema": { "type": "integer" } }, { "name": "to", "in": "query", "description": "End date. Set as UNIX timestamp in seconds.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } } } }, "/v1/usage/hosts": { "get": { "tags": [ "Usage v1" ], "summary": "List Usage by Host", "description": "Lists aggregated usage information for all hosts during a time period.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `log` | `read` | Lets you see which hosts are using the most of your log volume |", "operationId": "list-usage-host", "parameters": [ { "name": "from", "in": "query", "description": "Start date. Set as UNIX timestamp in seconds.", "required": true, "schema": { "type": "integer" } }, { "name": "to", "in": "query", "description": "End date. Set as UNIX timestamp in seconds.", "required": true, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "description": "Maximum amount of apps to retrieve.", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } } } }, "/v1/usage/hosts/{name}": { "get": { "tags": [ "Usage v1" ], "summary": "Get Usage by Host", "description": "Gets the aggregated usage information for a host matching the name provided as a path parameter,\nduring a time period. Returns null when not found.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `log` | `read` | Lets you check how much log volume a single host is using |", "operationId": "get-usage-host", "parameters": [ { "name": "name", "in": "path", "description": "The name of the app from which to get the aggregated usage data", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Start date. Set as UNIX timestamp in seconds.", "required": true, "schema": { "type": "integer" } }, { "name": "to", "in": "query", "description": "End date. Set as UNIX timestamp in seconds.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } } } }, "/v2/usage": { "get": { "tags": [ "Usage v2" ], "summary": "Retrieve account usage totals", "description": "Get aggregated usage information for an account's data during a time period.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `log` | `read` | Lets you see how much log volume the account has used over a period |", "operationId": "list-usage-v2", "parameters": [ { "name": "from", "in": "query", "description": "Start time. A date-time string as defined by the ISO 8601 date format. This date-time will be used to calculate the starting day; the exact time will not be used.", "required": true, "schema": { "type": "string" }, "example": "2023-01-01T12:00:00-05:00" }, { "name": "to", "in": "query", "description": "End time. A date-time string as defined by the ISO 8601 date format. This date-time will be used to calculate the ending day; the exact time will not be used.", "required": true, "schema": { "type": "string" }, "example": "2023-01-01T12:00:00-05:00" } ], "responses": { "200": { "$ref": "#/components/responses/usageResponse200" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "error": { "type": "string", "description": "Message indicating why the request is bad." }, "status": { "type": "string" } } } } } } } } }, "/v2/usage/apps": { "get": { "tags": [ "Usage v2" ], "summary": "List Usage By App", "description": "Lists aggregated usage information for all apps during a time period.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `log` | `read` | Lets you see which apps are using the most of your log volume |", "operationId": "list-usage-app-v2", "parameters": [ { "name": "from", "in": "query", "description": "Start time. A date-time string as defined by the ISO 8601 date format. This date-time will be used to calculate the starting day; the exact time will not be used.", "required": true, "schema": { "type": "string" }, "example": "2023-01-01T12:00:00-05:00" }, { "name": "to", "in": "query", "description": "End time. A date-time string as defined by the ISO 8601 date format. This date-time will be used to calculate the ending day; the exact time will not be used.", "required": true, "schema": { "type": "string" }, "example": "2023-01-01T12:00:00-05:00" }, { "name": "limit", "in": "query", "description": "Maximum amount of apps to retrieve.", "required": false, "schema": { "type": "integer" } }, { "name": "retention", "in": "query", "description": "Limit report to apps that contribute to a variable retention pool. Value must be a string indicating the retention pool duration, e.g. `7d` for a seven day retention pool.", "required": false, "schema": { "type": "string" }, "example": "7d" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "description": "The calculated starting time (exclusive) used internally." }, "to": { "type": "string", "description": "The calculated ending time (exclusive) used internally." }, "results": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the app." }, "total_bytes": { "type": "integer", "description": "The number of bytes of disk the app consumes over the time range." } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "error": { "type": "string", "description": "Message indicating why the request is bad." }, "status": { "type": "string" } } } } } } } } }, "/v2/usage/apps/{name}": { "get": { "tags": [ "Usage v2" ], "summary": "Get Usage By App", "description": "Gets the aggregated usage information for an app matching the name provided as a path parameter\nduring a time period. The `results` will either have a singular item, or be an empty array.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `log` | `read` | Lets you check how much log volume a single app is using |", "operationId": "get-usage-app-v2", "parameters": [ { "name": "name", "in": "path", "description": "The name of the app from which to get the aggregated usage data.", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Start time. A date-time string as defined by the ISO 8601 date format. This date-time will be used to calculate the starting day; the exact time will not be used.", "required": true, "schema": { "type": "string" }, "example": "2023-01-01T12:00:00-05:00" }, { "name": "to", "in": "query", "description": "End time. A date-time string as defined by the ISO 8601 date format. This date-time will be used to calculate the ending day; the exact time will not be used.", "required": true, "schema": { "type": "string" }, "example": "2023-01-01T12:00:00-05:00" }, { "name": "retention", "in": "query", "description": "Limit report to apps that contribute to a variable retention pool. Value must be a string indicating the retention pool duration, e.g. `7d` for a seven day retention pool.", "required": false, "schema": { "type": "string" }, "example": "7d" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "description": "The calculated starting time (exclusive) used internally." }, "to": { "type": "string", "description": "The calculated ending time (exclusive) used internally." }, "results": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the app." }, "total_bytes": { "type": "integer", "description": "The number of bytes of disk the app consumes over the time range." } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "error": { "type": "string", "description": "Message indicating why the request is bad." }, "status": { "type": "string" } } } } } } } } }, "/v2/usage/hosts": { "get": { "tags": [ "Usage v2" ], "summary": "List Usage by Host", "description": "Lists aggregated usage information for all hosts during a time period.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `log` | `read` | Lets you see which hosts are using the most of your log volume |", "operationId": "list-usage-host-v2", "parameters": [ { "name": "from", "in": "query", "description": "Start time. A date-time string as defined by the ISO 8601 date format. This date-time will be used to calculate the starting day; the exact time will not be used.", "required": true, "schema": { "type": "string" }, "example": "2023-01-01T12:00:00-05:00" }, { "name": "to", "in": "query", "description": "End time. A date-time string as defined by the ISO 8601 date format. This date-time will be used to calculate the ending day; the exact time will not be used.", "required": true, "schema": { "type": "string" }, "example": "2023-01-01T12:00:00-05:00" }, { "name": "limit", "in": "query", "description": "Maximum amount of hosts to retrieve.", "required": false, "schema": { "type": "integer" } }, { "name": "retention", "in": "query", "description": "Limit report to hosts that contribute to a variable retention pool. Value must be a string indicating the retention pool duration, e.g. `7d` for a seven day retention pool.", "required": false, "schema": { "type": "string" }, "example": "7d" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "description": "The calculated starting time (exclusive) used internally." }, "to": { "type": "string", "description": "The calculated ending time (exclusive) used internally." }, "results": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the host." }, "total_bytes": { "type": "integer", "description": "The number of bytes of disk the host consumes over the time range." } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "error": { "type": "string", "description": "Message indicating why the request is bad." }, "status": { "type": "string" } } } } } } } } }, "/v2/usage/hosts/{name}": { "get": { "tags": [ "Usage v2" ], "summary": "Get Usage by Host", "description": "Gets the aggregated usage information for a host matching the name provided as a path parameter\nduring a time period. The `results` will either have a singular item, or be an empty array.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `log` | `read` | Lets you check how much log volume a single host is using |", "operationId": "get-usage-host-v2", "parameters": [ { "name": "name", "in": "path", "description": "The name of the host from which to get the aggregated usage data.", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Start time. A date-time string as defined by the ISO 8601 date format. This date-time will be used to calculate the starting day; the exact time will not be used.", "required": true, "schema": { "type": "string" }, "example": "2023-01-01T12:00:00-05:00" }, { "name": "to", "in": "query", "description": "End time. A date-time string as defined by the ISO 8601 date format. This date-time will be used to calculate the ending day; the exact time will not be used.", "required": true, "schema": { "type": "string" }, "example": "2023-01-01T12:00:00-05:00" }, { "name": "retention", "in": "query", "description": "Limit report to hosts that contribute to a variable retention pool. Value must be a string indicating the retention pool duration, e.g. `7d` for a seven day retention pool.", "required": false, "schema": { "type": "string" }, "example": "7d" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "description": "The calculated starting time (exclusive) used internally." }, "to": { "type": "string", "description": "The calculated ending time (exclusive) used internally." }, "results": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the host." }, "total_bytes": { "type": "integer", "description": "The number of bytes of disk the host consumes over the time range." } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "error": { "type": "string", "description": "Message indicating why the request is bad." }, "status": { "type": "string" } } } } } } } } }, "/v2/usage/tags": { "get": { "tags": [ "Usage v2" ], "summary": "List Usage by Tag", "description": "Lists aggregated usage information for all tags during a time period.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `log` | `read` | Lets you see which tags are using the most of your log volume |", "operationId": "list-usage-tag-v2", "parameters": [ { "name": "from", "in": "query", "description": "Start time. A date-time string as defined by the ISO 8601 date format. This date-time will be used to calculate the starting day; the exact time will not be used.", "required": true, "schema": { "type": "string" }, "example": "2023-01-01T12:00:00-05:00" }, { "name": "to", "in": "query", "description": "End time. A date-time string as defined by the ISO 8601 date format. This date-time will be used to calculate the ending day; the exact time will not be used.", "required": true, "schema": { "type": "string" }, "example": "2023-01-01T12:00:00-05:00" }, { "name": "limit", "in": "query", "description": "Maximum amount of tags to retrieve.", "required": false, "schema": { "type": "integer" } }, { "name": "retention", "in": "query", "description": "Limit report to tags that contribute to a variable retention pool. Value must be a string indicating the retention pool duration, e.g. `7d` for a seven day retention pool.", "required": false, "schema": { "type": "string" }, "example": "7d" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "description": "The calculated starting time (exclusive) used internally." }, "to": { "type": "string", "description": "The calculated ending time (exclusive) used internally." }, "results": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the tag." }, "total_bytes": { "type": "integer", "description": "The number of bytes of disk the tag consumes over the time range." } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "error": { "type": "string", "description": "Message indicating why the request is bad." }, "status": { "type": "string" } } } } } } } } }, "/v2/usage/tags/{name}": { "get": { "tags": [ "Usage v2" ], "summary": "Get Usage by Tag", "description": "Gets the aggregated usage information for a tag matching the name provided as a path parameter\nduring a time period. The `results` will either have a singular item, or be an empty array.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `log` | `read` | Lets you check how much log volume a single tag is using |", "operationId": "get-usage-tag-v2", "parameters": [ { "name": "name", "in": "path", "description": "The name of the tag from which to get the aggregated usage data.", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Start time. A date-time string as defined by the ISO 8601 date format. This date-time will be used to calculate the starting day; the exact time will not be used.", "required": true, "schema": { "type": "string" }, "example": "2023-01-01T12:00:00-05:00" }, { "name": "to", "in": "query", "description": "End time. A date-time string as defined by the ISO 8601 date format. This date-time will be used to calculate the ending day; the exact time will not be used.", "required": true, "schema": { "type": "string" }, "example": "2023-01-01T12:00:00-05:00" }, { "name": "retention", "in": "query", "description": "Limit report to tags that contribute to a variable retention pool. Value must be a string indicating the retention pool duration, e.g. `7d` for a seven day retention pool.", "required": false, "schema": { "type": "string" }, "example": "7d" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "description": "The calculated starting time (exclusive) used internally." }, "to": { "type": "string", "description": "The calculated ending time (exclusive) used internally." }, "results": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the tag." }, "total_bytes": { "type": "integer", "description": "The number of bytes of disk the tag consumes over the time range." } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "error": { "type": "string", "description": "Message indicating why the request is bad." }, "status": { "type": "string" } } } } } } } } }, "/v1/config/keys": { "get": { "tags": [ "Keys" ], "summary": "Retrieve a list of all the keys", "description": "Retrieve a list of all the keys for an account. Supported key types include `ingestion` and\n`service`. Use the `type` parameter to filter which type of keys to retrieve.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `ingest_key` | `manage` | Lets you view the ingestion and service keys on an account, including their values |", "operationId": "list-key", "parameters": [ { "name": "type", "in": "query", "description": "The type of key to retrieve. Defaults to \"all\"", "schema": { "type": "string", "enum": [ "ingestion", "service", "all" ] } } ], "responses": { "200": { "description": "A list of keys is returned on success.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/keyResource" } } } } }, "400": { "description": "The supplied request is invalid or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errResponse" }, "example": { "error": "\"type\" must be one of [ingestion, service, all]", "code": "BadRequest", "status": "error" } } } } } }, "post": { "tags": [ "Keys" ], "summary": "Create a new key", "description": "Create a new key of the type specified by the `type` parameter. If a name is not supplied, one\nwill be auto generated.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `ingest_key` | `manage` | Lets you mint a new ingestion or service key for the account |", "operationId": "create-key", "parameters": [ { "name": "type", "in": "query", "description": "The type of key to be created", "required": true, "schema": { "type": "string", "enum": [ "ingestion", "service", "all" ] } } ], "requestBody": { "description": "Modifiable fields can be set in the request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/keysPut" } } }, "required": false }, "responses": { "200": { "description": "A new key was created successfully! The entire key resource is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/keyResource" } } } }, "400": { "description": "The supplied request is invalid or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errResponse" }, "example": { "error": "\"type\" is required", "code": "BadRequest", "status": "error" } } } } } } }, "/v1/config/keys/{id}": { "get": { "tags": [ "Keys" ], "summary": "Retrieve a specific key", "description": "Retrieves a specific key by its `id`.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `ingest_key` | `manage` | Lets you look up a single key, its value included |", "operationId": "get-key", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the key to retrieve", "schema": { "$ref": "#/components/schemas/keyId" } } ], "responses": { "200": { "description": "The key with the supplied `id` was found, the entire resource is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/keyResource" } } } }, "404": { "description": "The specified key was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errResponse" }, "example": { "error": "Key with id 629eb5369e5b231f51d3830f was not found", "code": "NotFound", "status": "error" } } } } } }, "delete": { "tags": [ "Keys" ], "summary": "Delete a specific key", "description": "Delete a specific key by its `id`.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `ingest_key` | `manage` | Lets you revoke a key, which breaks anything still using it immediately |", "operationId": "delete-key", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the key to delete", "schema": { "$ref": "#/components/schemas/keyId" } } ], "responses": { "200": { "description": "The key was deleted successfully, a simple status is returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The status of the request in a human-readable form", "example": "Key deleted successfully" }, "deleted": { "type": "boolean", "description": "Indicates whether the key was deleted", "example": true } } } } } }, "404": { "description": "The specified key was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errResponse" }, "example": { "error": "Key with id 629eb5369e5b231f51d3830f was not found", "code": "NotFound", "status": "error" } } } } } }, "put": { "tags": [ "Keys" ], "summary": "Update one or more fields of a key resource", "description": "Updates all of the fields described in the request body of the specified key. Fields left out of\nthe body will remain unaffected.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `ingest_key` | `manage` | Lets you rename a key or adjust its settings |", "operationId": "put-key", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the key to update", "schema": { "$ref": "#/components/schemas/keyId" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/keysPut" } } } }, "responses": { "200": { "description": "The update was successful; the key resource is returned with updated fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/keyResource" } } } }, "400": { "description": "The supplied request is invalid or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errResponse" }, "example": { "error": "\"name\" length must be less than or equal to 30 characters long", "code": "BadRequest", "status": "error" } } } }, "404": { "description": "The specified key was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errResponse" }, "example": { "error": "Key with id 629eb5369e5b231f51d3830f was not found", "code": "NotFound", "status": "error" } } } } } } }, "/v1/config/categories/{type}": { "get": { "tags": [ "Configuration" ], "summary": "List Categories", "description": "Returns all Categories of a type.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `category` | `read` | Lets you see what categories your team has set up for this type |", "operationId": "list-categories", "parameters": [ { "name": "type", "in": "path", "description": "Category type. Must be [views, boards, screens]", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } } }, "post": { "tags": [ "Configuration" ], "summary": "Create New Category", "description": "Creates a new category of this type.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `category` | `write` | Lets you add a category so things of this type can be filed under it |", "operationId": "create-category", "parameters": [ { "name": "type", "in": "path", "description": "Category type. Must be [views, boards, screens]", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/categoryName" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } } } }, "/v1/config/categories/{type}/{id}": { "get": { "tags": [ "Configuration" ], "summary": "Get Category", "description": "Get a specific category\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `category` | `read` | Lets you look at a single category and what's filed under it |", "operationId": "get-category", "parameters": [ { "name": "type", "in": "path", "description": "Category type. Must be [views, boards, screens]", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "ID of category.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } } }, "put": { "tags": [ "Configuration" ], "summary": "Update Category", "description": "Update a specific category.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `category` | `write` | Lets you rename a category or change what's filed under it |", "operationId": "update-category", "parameters": [ { "name": "type", "in": "path", "description": "Category type. Must be [views, boards, screens]", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "ID of category.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/categoryName" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } } }, "delete": { "tags": [ "Configuration" ], "summary": "Delete Category", "description": "Use this method to delete a category.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `category` | `manage` | Lets you delete a category, leaving anything filed under it uncategorized |", "operationId": "delete-category", "parameters": [ { "name": "type", "in": "path", "description": "Category type. Must be [views, boards, screens]", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "ID of category.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } } } }, "/v1/config/index-rate": { "get": { "tags": [ "Index Rate Alert" ], "summary": "Get Index Rate Alert", "description": "Gets the configuration for an Index Rate Alert\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `index_rate_alert` | `read` | Lets you see the threshold your account alerts on and who hears about it |", "operationId": "get-index-rate-alert", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/indexRateAlertConfigResponse" } } } }, "400": { "description": "Bad request", "content": {} }, "500": { "description": "Internal Server error occurred when trying to fetch index rate alerts", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/errPropsDefault" } } } } } }, "put": { "tags": [ "Index Rate Alert" ], "summary": "Update Index Rate Alert", "description": "Use this method to update an index rate alert. You can change the alert's configuration details.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `index_rate_alert` | `write` | Lets you raise or lower the threshold, and change who gets told when it's crossed |", "operationId": "update-index-rate-alert", "requestBody": { "description": "Request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/indexRateAlertConfigResponse" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/indexRateAlertConfigResponse" } } } }, "400": { "description": "Bad request", "content": {} }, "500": { "description": "Internal Server error occurred when trying to fetch index rate alerts", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/errPropsDefault" } } } } }, "deprecated": false, "x-codegen-request-body-name": "configRequest" } }, "/v1/config/members": { "get": { "tags": [ "Members" ], "summary": "Lists all members", "description": "Retrieves all of the current members in an organization and returns their email, role, and\ngroups.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `user` | `read` | Lets you see who's on the team and what role and groups each person has |", "operationId": "list-members", "responses": { "200": { "description": "A list of members is returned on success.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/memberResource" } } } } } } }, "post": { "tags": [ "Members" ], "summary": "Creates a new member", "description": "Create a new user and add to the team by providing 'email', 'role' and an optional list of RBAC\ngroups.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `account` | `manage` | Lets you add someone to the org and set their role and groups |", "operationId": "create-member", "requestBody": { "description": "Request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/memberResource" } } }, "required": true }, "responses": { "200": { "description": "A new member was created successfully! Entire memberResource is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/memberResource" } } } }, "400": { "description": "The supplied request is invalid or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errResponse" }, "example": { "error": "\"role\" is required", "code": "BadRequest", "status": "error" } } } }, "409": { "description": "The supplied request leads to an invalid state. The returned error will contain more helpful information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errPropsDefault" }, "example": { "code": "Conflict", "error": "Admins can\\'t be assigned to any groups" } } } } } } }, "/v1/config/members/{email}": { "get": { "tags": [ "Members" ], "summary": "Retrieve a member", "description": "Returns the role and groups of the specified member.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `user` | `read` | Lets you look up one person's role and group assignments |", "operationId": "get-member", "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/memberEmail" } } ], "responses": { "200": { "description": "The member with the supplied `email` was found, the entire resource is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/memberResource" } } } }, "404": { "description": "The specified member was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errResponse" }, "example": { "error": "Member \"fakeaccount@mezmo.com\" not found", "code": "NotFound", "status": "error" } } } } } }, "delete": { "tags": [ "Members" ], "summary": "Delete a member", "description": "Removes a member from the organization. This does not delete the user.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `account` | `manage` | Lets you take someone off the team; their user account itself sticks around |", "operationId": "delete-member", "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/memberEmail" } } ], "responses": { "200": { "description": "The member was removed successfully, a simple status is returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The status of the request in a human-readable form", "example": "Member removed successfully." }, "deleted": { "type": "boolean", "description": "Indicates whether the member was deleted", "example": true } } } } } }, "404": { "description": "The specified member was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errResponse" }, "example": { "error": "The provided email is not an active member of this account.", "code": "NotFound", "status": "error" } } } }, "409": { "description": "The specified member (owner) cannot be removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errResponse" }, "example": { "error": "The owner of the account can\\'t be removed.", "code": "Conflict", "status": "error" } } } } } }, "put": { "tags": [ "Members" ], "summary": "Update a member", "description": "Updates all the fields described in the request body of the specified member. Creates a member\nif the member doesn't exist already. Fields left out of the body will remain unaffected.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `account` | `manage` | Lets you change someone's role or groups, or add them to the org if they aren't in it yet |", "operationId": "put-member", "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/memberEmail" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/membersPut" } } } }, "responses": { "200": { "description": "The update was successful; the member resource is returned with updated fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/memberResource" } } } }, "400": { "description": "The supplied request is invalid or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errResponse" }, "example": { "error": "\"value\" must contain at least one of [role, groups]", "code": "BadRequest", "status": "error" } } } }, "409": { "description": "The supplied request leads to an invalid state. The returned error will contain more helpful information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errResponse" }, "example": { "error": "Admins can\\'t be assigned to any groups", "code": "Conflict", "status": "error" } } } } } } }, "/v1/enterprise/account": { "get": { "security": [ { "enterpriseServiceKeyAuth": [] } ], "tags": [ "Enterprise" ], "summary": "List all accounts", "description": "Retrieves a list of all child organizations that belong to the enterprise.", "operationId": "list-orgs", "responses": { "200": { "description": "A list of child organizations is returned on success.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/enterpriseResource" } } } } }, "400": { "description": "A poorly formatted request returns with a `BadRequest` code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errResponse" }, "example": { "error": "\"test\" is not allowed", "code": "BadRequest", "status": "error" } } } } } }, "post": { "security": [ { "enterpriseServiceKeyAuth": [], "basicAuth": [] }, { "enterpriseServiceKeyAuth": [], "servicekeyAuth": [] } ], "tags": [ "Enterprise" ], "summary": "Attach a child organization to an enterprise", "description": "Attaches an existing organization to an enterprise. The `retention` and `owner` field are optional, and will be defaulted if not specified. To specify which child organization to attach, one of its service keys must be supplied through our typical service key authorization schema; either as basic authorization or through the `servicekey` header.", "operationId": "create-org", "requestBody": { "description": "Request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/enterprisePut" } } }, "required": true }, "responses": { "200": { "description": "Child organization successfully attached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/enterpriseResource" } } } }, "400": { "description": "A poorly formatted request returns with a `BadRequest` code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errResponse" }, "example": { "error": "Service Key Validation Error: Invalid or deactivated servicekey", "code": "BadRequest", "status": "error" } } } }, "409": { "description": "The supplied request leads to an invalid state. The returned error will contain more helpful information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errPropsDefault" }, "example": { "code": "Conflict", "error": "No contract found for this enterprise.", "status": "error" } } } } } } }, "/v1/enterprise/account/{accountId}": { "get": { "security": [ { "enterpriseServiceKeyAuth": [] } ], "tags": [ "Enterprise" ], "summary": "Get details of a child organization", "description": "Retrieves a specific child organization by its id. If the organization does not belong to the enterprise, a 404 error is returned.", "operationId": "get-org", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/accountId" } } ], "responses": { "200": { "description": "The child organization was found and returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/enterpriseResource" } } } } } }, "put": { "security": [ { "enterpriseServiceKeyAuth": [] } ], "tags": [ "Enterprise" ], "summary": "Update Child Organization Contract", "description": "Makes an update to the specified child organization. Used to modify the current retention with the `retention` field or the current owner with the `owner` field.", "operationId": "put-org", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/accountId" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/enterprisePut" } } } }, "responses": { "200": { "description": "The account was found, the enterpriseId and retention details are updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/enterpriseResource" } } } }, "400": { "description": "Invalid body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errResponse" }, "example": { "error": "\"plan\" is not allowed", "code": "BadRequest", "status": "error" } } } }, "404": { "description": "Unable to update account which not belong to enterprise", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errResponse" }, "example": { "error": "Invalid Account.", "code": "NotFound", "status": "error" } } } }, "409": { "description": "Return error when account does not have contract tier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errResponse" }, "example": { "error": "No contract found for this account.", "code": "Conflict", "status": "error" } } } } } }, "delete": { "security": [ { "enterpriseServiceKeyAuth": [] } ], "tags": [ "Enterprise" ], "summary": "Detach a child org from Enterprise", "description": "Detaches a child organization from the enterprise. The child organization is not deleted and can continue to work afterwards.", "operationId": "delete-org", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/accountId" } } ], "responses": { "200": { "description": "The child org was removed successfully, a simple status is returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/accountId" } } } } } }, "400": { "description": "Invalid body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errResponse" }, "example": { "error": "\"account_id\" is not allowed", "code": "BadRequest", "status": "error" } } } }, "409": { "description": "Account enterprise id mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errResponse" }, "example": { "error": "Invalid Account", "code": "Conflict", "status": "error" } } } } } } }, "/v1/enterprise/keys": { "get": { "security": [ { "enterpriseServiceKeyAuth": [] } ], "tags": [ "Enterprise" ], "summary": "List all enterprise keys", "description": "Retrieves all keys of the enterprise", "operationId": "list-enterpriseKeys", "responses": { "200": { "description": "A list of enterprise service keys is returned on success.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/keyResource" } } } } }, "400": { "description": "Invalid query params", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errResponse" }, "example": { "error": "\"value\" must be of type object", "code": "BadRequest", "status": "error" } } } } } }, "post": { "security": [ { "enterpriseServiceKeyAuth": [] } ], "tags": [ "Enterprise" ], "summary": "Generate a new Key for the Enterprise", "description": "Generate a new ServiceKey for the enterprise ", "operationId": "create-enterpriseKey", "responses": { "200": { "description": "A new Service Key is generated and saved to the Key collection ", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/keyResource" } } } }, "400": { "description": "The supplied request is invalid or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errResponse" }, "example": { "error": "\"param\" is not allowed", "code": "BadRequest", "status": "error" } } } }, "409": { "description": "The supplied request leads to an invalid state. The returned error will contain more helpful information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errPropsDefault" }, "example": { "code": "Conflict", "error": "This account is not allowed more than 50 enterprise-service keys.", "status": "error" } } } } } } }, "/v1/enterprise/keys/{id}": { "get": { "security": [ { "enterpriseServiceKeyAuth": [] } ], "tags": [ "Enterprise" ], "summary": "Retrieve a specific entperise key", "description": "Retrieves a specific enterprise key by its `id`.", "operationId": "get-entperiseKey", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/keyId" } } ], "responses": { "200": { "description": "The key with the supplied `id` was found, the entire resource is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/keyResource" } } } }, "400": { "description": "Invalid query params", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errResponse" }, "example": { "error": "\"value\" must be of type object", "code": "BadRequest", "status": "error" } } } } } }, "delete": { "security": [ { "enterpriseServiceKeyAuth": [] } ], "tags": [ "Enterprise" ], "summary": "Delete an Enterprise ServiceKey", "description": "Delete an Enterprise ServiceKey from list of keys for the Enterprise", "operationId": "delete-entperiseKey", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/keyId" } } ], "responses": { "200": { "description": "The Enterprise ServiceKey was deleted successfully, a simple status is returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The status of the request in a human-readable form", "example": "Key deleted successfully." }, "deleted": { "type": "boolean", "description": "Indicates whether the member was deleted", "example": true } } } } } } } } }, "/v1/config/screen": { "get": { "tags": [ "Screens" ], "summary": "List all screens", "description": "List all screens in a short form that only includes the screen id and title.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `screen` | `read` | Lets you see what screens your team has built |", "operationId": "list-screens", "responses": { "200": { "description": "A list of screens is returned on success.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/screenListResource" } } } } } } }, "post": { "tags": [ "Screens" ], "summary": "Creates a new screen", "description": "Creates a new screen\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `screen` | `write` | Lets you put together a new screen of your own |", "operationId": "create-screen", "requestBody": { "description": "Request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/screenResource" } } }, "required": true }, "responses": { "200": { "description": "A new screen was created successfully! Entire memberResource is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/screenResource" } } } }, "400": { "description": "The supplied request is invalid or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errResponse" }, "example": { "error": "\"ratio\" is required", "code": "BadRequest", "status": "error" } } } } } } }, "/v1/config/screen/{id}": { "get": { "tags": [ "Screens" ], "summary": "Retrieve a screen", "description": "Retrieve a specific screen\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `screen` | `read` | Lets you open a screen and see what's on it |", "operationId": "get-screen", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A fully detailed screen resource for the matching id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/screenResource" } } } }, "404": { "description": "The specified screen was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errResponse" }, "example": { "error": "Unable to find screen with this id on this account", "code": "NotFound", "status": "error" } } } } } }, "delete": { "tags": [ "Screens" ], "summary": "Delete a screen", "description": "Deletes a screen\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `screen` | `manage` | Lets you delete a screen, which removes it for everyone on the account |", "operationId": "delete-screen", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The screen was deleted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "description": "Indicates whether the screen was deleted", "example": true } } } } } }, "404": { "description": "The specified screen was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errResponse" }, "example": { "error": "Screen Not Found", "code": "NotFound", "status": "error" } } } } } } }, "/v1/config/parsing-template": { "get": { "tags": [ "Parsing Template" ], "summary": "List Parsing Templates", "description": "Get a list of custom parsing templates.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `custom_parsing` | `read` | Lets you see what custom parsing your team has set up |", "operationId": "list-parsing-template", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "templateid": { "type": "string", "example": "0000000000" }, "account": { "$ref": "#/components/schemas/accountId" }, "name": { "type": "string", "description": "Name of the template" } } } } } } }, "400": { "description": "Bad request", "content": {} } } } }, "/v1/config/parsing-template/{templateId}": { "get": { "tags": [ "Parsing Template" ], "summary": "Get Parsing Template", "description": "Gets the configuration for a specific parsing template.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `custom_parsing` | `read` | Lets you look at one template and the fields it pulls out of a line |", "operationId": "get-parsing-template", "parameters": [ { "name": "templateId", "in": "path", "description": "ID of a template.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "templateid": { "type": "string", "example": "0000000000" }, "account": { "$ref": "#/components/schemas/accountId" }, "name": { "type": "string", "description": "Name of the template" }, "priority": { "type": "number" }, "draft": { "type": "boolean" }, "active": { "type": "boolean" }, "legacy": { "type": "boolean" }, "query": { "type": "string" }, "line": { "type": "string" }, "draftof": { "type": "string" }, "operators": { "$ref": "#/components/schemas/templateOperators" } } } } } }, "400": { "description": "Bad request", "content": {} } } }, "delete": { "tags": [ "Parsing Template" ], "summary": "Delete Parsing Template", "description": "Use this method to delete a parsing template.\n\n### Permissions\n\n| Resource | Permission | Usage |\n| --- | --- | --- |\n| `custom_parsing` | `manage` | Lets you delete a template, so new lines stop getting those fields pulled out |", "operationId": "delete-parsing-template", "parameters": [ { "name": "templateId", "in": "path", "description": "ID of the template.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } } } } }, "400": { "description": "Bad request", "content": {} } }, "deprecated": false } } }, "components": { "responses": { "streamErrResponse401": { "description": "Not Authorized", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/errPropsDefault" } }, "application/json": { "example": { "code": "NotAuthorized", "error": "Missing Credentials" } } } }, "streamErrResponse500": { "description": "Internal Server Error", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/errPropsDefault" } }, "application/json": { "example": { "code": "ServerError", "error": "Database operation failed to get stream configuration." } } } }, "streamResponse200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/streamConfigCommon" } }, "application/json": { "example": { "brokers": [ "broker-1.kafka.svc00.env.eventstreams.cloud.ibm.com:9093" ], "topic": "topic", "user": "token", "status": "active" } } } }, "standardResponse200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "OK" } } } } } }, "usageResponse200": { "description": "OK", "content": { "application/json": { "example": { "from": "2022-12-31T23:59:59.999Z", "to": "2023-02-01T00:00:00.000Z", "results": { "plan_bytes": 123000, "restored_bytes": 1000, "7d_vr_bytes": 1000 } }, "schema": { "type": "object", "properties": { "from": { "type": "string", "description": "The calculated starting time (exclusive) used internally." }, "to": { "type": "string", "description": "The calculated ending time (exclusive) used internally." }, "results": { "type": "object", "properties": { "plan_bytes": { "type": "number" }, "restored_bytes": { "type": "number" }, "xd_vr_bytes": { "type": "number", "description": "The number of bytes of logs stored for this variable retention type where x is 3, 7, 14, or 30 day" } } } } } } } }, "usageResponseWORestored200": { "description": "OK", "content": { "application/json": { "example": { "from": "2022-12-31T23:59:59.999Z", "to": "2023-02-01T00:00:00.000Z", "results": { "plan_bytes": 123000 } }, "schema": { "type": "object", "properties": { "from": { "type": "string", "description": "The calculated starting time (exclusive) used internally." }, "to": { "type": "string", "description": "The calculated ending time (exclusive) used internally." }, "results": { "type": "object", "properties": { "plan_bytes": { "type": "number" } } } } } } } } }, "schemas": { "password": { "type": "string", "description": "Password provided in credentials for authorization", "format": "password" }, "hostName": { "type": "string", "description": "Host name of the source." }, "mac": { "type": "string", "description": "The network mac address of the host computer.", "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$", "example": "01:02:03:04:ab:cd" }, "ip": { "type": "string", "description": "The local IP address of the host computer (ipv4 or ipv6)", "example": "10.0.1.111" }, "now": { "type": "string", "description": "Field format in date-time notation. The source UNIX timestamp in milliseconds at the time of the request. Used to calculate time drift." }, "tags": { "type": "string", "description": "Tags that are used to dynamically group hosts." }, "line": { "type": "string", "description": "Text of the log line." }, "timestamp": { "type": "string", "description": "UNIX timestamp, including milliseconds, when the log entry was recorded." }, "app": { "type": "string", "description": "Name of the application that generates the log line." }, "level": { "type": "string", "description": "Set a value for the level. For example, sample values for this parameter are INFO, WARNING, ERROR." }, "meta": { "type": "string", "description": "This field is reserved for custom information that is associated with a log line. To add metadata to an API call, specify the meta field under the lines object. Metadata can be viewed inside that line's context." }, "viewId": { "type": "string", "description": "ID of a view." }, "name": { "type": "string", "description": "Name of a view." }, "from": { "type": "string", "description": "Start time. Set as UNIX timestamp in seconds or milliseconds." }, "to": { "type": "string", "description": "End time. Set as UNIX timestamp in seconds or milliseconds." }, "size": { "type": "string", "description": "Number of log lines to include in the export." }, "hosts": { "type": "string", "description": "Comma-separated list of hosts." }, "apps": { "type": "string", "description": "Comma-separated list of applications." }, "levels": { "type": "string", "description": "Comma-separated list of log levels." }, "query": { "type": "string", "description": "Search query." }, "prefer": { "type": "string", "description": "Defines the log lines that you want to export. Valid values are head, first log lines, and tail, last log lines. If not specified, defaults to tail." }, "email": { "type": "string", "description": "Specifies the email with the downloadable link of your export. By default, the log lines are streamed." }, "ownerEmail": { "type": "string", "description": "The email of a user to be given owner privileges of an account.", "example": "owner@example.org" }, "plan": { "type": "string", "description": "The name of a plan.", "example": "enterprise" }, "emailSubject": { "type": "string", "description": "Use to set the subject of the email. Use to represent a space. For example, a sample value is Export logs." }, "integration": { "type": "string", "description": "Defines the type of notification channel. Valid values are: `email`, `webhook`, `slack`, and `pagerduty`" }, "archiveintegration": { "type": "string", "description": "Defines the type of archive destination. Valid values are: `ibm`, `s3`, `gcs`, `dos`, `azblob`, and `swift`" }, "pagination_id": { "type": "string", "description": "ID that indicates which page of results to be retrieved. Leave empty for the initial export request." }, "emails": { "type": "string", "description": "Comma-separated list of email addresses." }, "url": { "type": "string", "description": "Webhook URL." }, "key": { "type": "string", "description": "PagerDuty key." }, "triggerlimit": { "type": "string", "description": "Specify the number of log lines that match the view's filtering and search criteria. When the number of log lines is reached, an alert is triggered." }, "triggerinterval": { "type": "string", "description": "Specify how often to trigger an alert. Valid values are: 30 seconds, 1 minute, 5 minutes, 15 minutes, 30 minutes, 1 hour, 6 hours, 12 hours, 24 hours" }, "autoresolve": { "type": "boolean", "description": "Set to true if you want the set a condition to resolve the incident that was raised by this alert. This property only applies to PagerDuty." }, "autoresolvelimit": { "type": "string", "description": "Specify the number of log lines that match the view's filtering and search criteria. When the number of log lines is reached, this incident will be set to resolved in PagerDuty." }, "autoresolveinterval": { "type": "string", "description": "Interval of time to aggregate and check # of matched lines against the auto resolve limit. Valid values are: 30 seconds, 1 minute, 5 minutes, 15 minutes, 30 minutes, 1 hour, 6 hours, 12 hours, 24 hours, 25 hours." }, "immediate": { "type": "boolean", "description": "Set to true if you want the trigger condition to be evaluated as soon as the triggerlimit is reached." }, "terminal": { "type": "boolean", "description": "Set to true if you want the trigger condition to be evaluated after the time that you specify in the triggerinterval field is reached." }, "operator": { "type": "string", "description": "Type of alert. Valid values are: `presence`and `absence`." }, "timezone": { "type": "string", "description": "Timezone used to report timestamps. This can be any value defined in the tz database https://en.wikipedia.org/wiki/List_of_tz_database_time_zones.", "example": "America/Chicago, EST, Etc/UTC, etc..." }, "method": { "type": "string", "description": "WebHook method such as POST.", "enum": [ "POST", "PUT", "PATCH" ] }, "presetid": { "type": "string", "description": "ID of a preset alert." }, "category": { "type": "string", "description": " Logical name that you can use to group views." }, "groupname": { "type": "string", "description": "Name of a log group." }, "groupId": { "type": "string", "description": "ID a log group." }, "ruleId": { "type": "string", "description": "ID an exclusion rule." }, "accessscope": { "type": "string", "description": "Query that determines the data that is visible to members of a group." }, "keyId": { "type": "string", "description": "The ID of the key", "example": "629e3f7e62295be60488fb26" }, "keyValue": { "type": "string", "description": "A secret key which can be used to authenticate requests to Mezmo.", "example": "7b273eb8adc962f2711ad760730debb0" }, "keyCreated": { "type": "integer", "description": "The time the key was created as a Unix timestamp in milliseconds", "example": 1654538253244 }, "keyType": { "type": "string", "description": "The type of the key", "enum": [ "ingestion", "service" ], "example": "ingestion" }, "keyName": { "type": "string", "description": "A user friendly name for the key", "maxLength": 30, "example": "servergroup_0_ingestion" }, "memberEmail": { "type": "string", "description": "Email of a member", "example": "testemail@gmail.com" }, "role": { "type": "string", "description": "role of member. Owner shall not be created or set through api", "enum": [ "owner", "admin", "readonly", "member" ], "example": "member" }, "rbacGroupId": { "type": "string", "description": "The ID of one of RBAC groups that belong to the account" }, "accountId": { "type": "string", "description": "Account number of the organization", "example": "0000000000" }, "enterpriseId": { "type": "string", "description": "Unique Id of the enterprise organization", "example": "0000000000" }, "retention": { "type": "integer", "description": "Current retention period selected for the child organization", "example": 7 }, "retentionPeriods": { "type": "array", "items": { "$ref": "#/components/schemas/retention" }, "description": "Available log retention options for the child organization" }, "headers": { "type": "object", "properties": { "timestamp": { "$ref": "#/components/schemas/X-MY-HEADER" } } }, "bodyTemplate": { "type": "object", "properties": { "timestamp": { "$ref": "#/components/schemas/my_log_lines" } } }, "X-MY-HEADER": { "type": "string", "description": "Header value" }, "my_log_lines": { "type": "string", "description": "Define the webhook body." }, "channel": { "type": "object", "properties": { "integration": { "$ref": "#/components/schemas/integration" }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/emails" } }, "url": { "$ref": "#/components/schemas/url" }, "key": { "$ref": "#/components/schemas/key" }, "triggerlimit": { "$ref": "#/components/schemas/triggerlimit" }, "triggerinterval": { "$ref": "#/components/schemas/triggerinterval" }, "immediate": { "$ref": "#/components/schemas/immediate" }, "terminal": { "$ref": "#/components/schemas/terminal" }, "operator": { "$ref": "#/components/schemas/operator" }, "timezone": { "$ref": "#/components/schemas/timezone" }, "method": { "$ref": "#/components/schemas/method" }, "headers": { "$ref": "#/components/schemas/headers" }, "bodyTemplate": { "$ref": "#/components/schemas/bodyTemplate" }, "autoresolve": { "$ref": "#/components/schemas/autoresolve" }, "autoresolveinterval": { "$ref": "#/components/schemas/autoresolveinterval" }, "autoresolvelimit": { "$ref": "#/components/schemas/autoresolvelimit" } } }, "configRequest": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/name" }, "query": { "$ref": "#/components/schemas/query" }, "hosts": { "type": "array", "items": { "$ref": "#/components/schemas/hosts" } }, "apps": { "type": "array", "items": { "$ref": "#/components/schemas/apps" } }, "levels": { "type": "array", "items": { "$ref": "#/components/schemas/levels" } }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/tags" } }, "category": { "type": "array", "items": { "$ref": "#/components/schemas/category" } }, "presetid": { "$ref": "#/components/schemas/presetid" }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/channel" } } }, "required": [ "name" ], "x-examples": { "example-1": { "name": "string", "query": "string", "hosts": "string", "apps": "string", "levels": "string", "tags": "string", "category": [ "string" ], "presetid": "string", "channels": [ { "integration": "string", "email": "string", "key": "string", "triggerlimit": "string", "triggerinterval": "string", "immediate": true, "terminal": true, "operator": "string", "timezone": "string", "method": "string", "headers": { "timestamp": "string" }, "bodyTemplate": { "timestamp": "string" } } ] } } }, "presetRequest": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/name" }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/channel" } } } }, "categoryName": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/name" } } }, "archivingConfigRequest": { "type": "object", "properties": { "integration": { "$ref": "#/components/schemas/integration" }, "bucket": { "$ref": "#/components/schemas/bucket" }, "endpoint": { "$ref": "#/components/schemas/endpoint" }, "apikey": { "$ref": "#/components/schemas/apikey" }, "resourceinstanceid": { "$ref": "#/components/schemas/resourceinstanceid" }, "accountname": { "$ref": "#/components/schemas/accountname" }, "accountkey": { "$ref": "#/components/schemas/accountkey" }, "projectid": { "$ref": "#/components/schemas/projectid" }, "space": { "$ref": "#/components/schemas/space" }, "accesskey": { "$ref": "#/components/schemas/accesskey" }, "secretkey": { "$ref": "#/components/schemas/secretkey" }, "authurl": { "$ref": "#/components/schemas/authurl" }, "expires": { "$ref": "#/components/schemas/expires" }, "username": { "$ref": "#/components/schemas/username" }, "password": { "$ref": "#/components/schemas/password" }, "tenantname": { "$ref": "#/components/schemas/tenantname" } }, "x-examples": { "example-1": { "integration": "string", "bucket": "string", "endpoint": "string", "apikey": "string", "resourceinstanceid": "string" } } }, "brokers": { "minItems": 1, "type": "array", "description": "List of URLs referencing Kafka broker connections via SASL_SSL", "items": { "minLength": 1, "type": "string" } }, "topic": { "minLength": 1, "type": "string", "description": "Name of the relevant Kafka topic category storing log records" }, "stream_user": { "minLength": 1, "type": "string", "description": "Username in provided credentials to authorize access to brokers" }, "stream_password": { "minLength": 1, "type": "string", "description": "Password in provided credentials to authorize access to brokers", "format": "password" }, "streamConfigCommon": { "required": [ "brokers", "topic", "user" ], "type": "object", "properties": { "brokers": { "$ref": "#/components/schemas/brokers" }, "topic": { "$ref": "#/components/schemas/topic" }, "user": { "$ref": "#/components/schemas/stream_user" }, "status": { "type": "string", "description": "Enumerated (binary) string representing whether or not the stream config is active", "readOnly": true, "enum": [ "active", "inactive" ] } } }, "streamConfigRequest": { "description": "Contains settings needed to set up connection(s) to Kafka brokers", "allOf": [ { "$ref": "#/components/schemas/streamConfigCommon" }, { "required": [ "password" ], "type": "object", "properties": { "password": { "$ref": "#/components/schemas/stream_password" } } } ] }, "streamExclusionRequest": { "required": [ "title" ], "type": "object", "properties": { "hosts": { "type": "array", "items": { "$ref": "#/components/schemas/hosts" } }, "apps": { "type": "array", "items": { "$ref": "#/components/schemas/apps" } }, "title": { "minLength": 1, "type": "string" }, "active": { "type": "boolean", "default": false }, "indexonly": { "type": "boolean", "default": true }, "query": { "$ref": "#/components/schemas/query" }, "id": { "minLength": 1, "type": "string", "readOnly": true } }, "description": "", "x-examples": { "example-1": { "hosts": [ "host-1", "host-2" ], "apps": [ "app-1", "app-2" ], "title": "title", "active": false, "query": "query", "id": "0000000" } } }, "groupsRequest": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/groupname" }, "accessScopes": { "$ref": "#/components/schemas/accessscope" } } }, "ingestlines": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "required": [ "line" ], "properties": { "timestamp": { "$ref": "#/components/schemas/timestamp" }, "line": { "$ref": "#/components/schemas/line" }, "app": { "$ref": "#/components/schemas/app" }, "level": { "$ref": "#/components/schemas/level" }, "meta": { "$ref": "#/components/schemas/meta" } } } } } }, "indexRateAlertWebhookConfig": { "type": "object", "properties": { "url": { "$ref": "#/components/schemas/url" }, "method": { "$ref": "#/components/schemas/method" }, "headers": { "$ref": "#/components/schemas/headers" }, "bodyTemplate": { "$ref": "#/components/schemas/bodyTemplate" } } }, "indexRateAlertConfig": { "type": "object", "properties": { "max_lines": { "type": "integer", "description": "The number of lines required in order to trigger the alert." }, "max_z_score": { "type": "integer", "description": "The number of standard deviations above the 30 day average lines in order to trigger the alert." }, "threshold_alert": { "type": "string", "description": "Determines if you want alerts to be triggered if both the max lines and standard deviation have been triggered, or if one of the thresholds has been reached.", "enum": [ "separate", "both" ] }, "frequency": { "type": "string", "description": "Notify recipients once per hour, or once per day, (starting when the threshold is passed the first time) until the index rate drops below the thresholds. When the index rate drops below the thresholds, alerting stops.", "enum": [ "hourly", "daily" ] }, "channels": { "type": "object", "properties": { "email": { "type": "array", "items": { "$ref": "#/components/schemas/emails" } }, "pagerduty": { "type": "array", "items": { "$ref": "#/components/schemas/key" } }, "slack": { "type": "array", "items": { "$ref": "#/components/schemas/url" } }, "webhook": { "type": "array", "items": { "$ref": "#/components/schemas/indexRateAlertWebhookConfig" } } } }, "enabled": { "type": "boolean" } } }, "indexRateAlertWebhookConfigResponse": { "type": "object", "properties": { "url": { "$ref": "#/components/schemas/url" }, "method": { "$ref": "#/components/schemas/method" }, "headers": { "$ref": "#/components/schemas/headers" }, "bodyTemplate": { "type": "string" } } }, "indexRateAlertConfigResponse": { "type": "object", "properties": { "max_lines": { "type": "integer", "description": "The number of lines required in order to trigger the alert." }, "max_z_score": { "type": "integer", "description": "The number of standard deviations above the 30 day average lines in order to trigger the alert." }, "threshold_alert": { "type": "string", "description": "Determines if you want alerts to be triggered if both the max lines and standard deviation have been triggered, or if one of the thresholds has been reached.", "enum": [ "separate", "both" ] }, "frequency": { "type": "string", "description": "Notify recipients once per hour, or once per day, (starting when the threshold is passed the first time) until the index rate drops below the thresholds. When the index rate drops below the thresholds, alerting stops.", "enum": [ "hourly", "daily" ] }, "channels": { "type": "object", "properties": { "email": { "type": "array", "items": { "$ref": "#/components/schemas/emails" } }, "pagerduty": { "type": "array", "items": { "$ref": "#/components/schemas/key" } }, "slack": { "type": "array", "items": { "$ref": "#/components/schemas/url" } }, "webhook": { "type": "array", "items": { "$ref": "#/components/schemas/indexRateAlertWebhookConfigResponse" } } } }, "enabled": { "type": "boolean" } } }, "errCode": { "type": "string", "description": "Entity used as an arbitrary classifier of the error encountered" }, "errMsg": { "type": "string", "description": "Error information surfaced to end user(s) in the response" }, "errValidation": { "type": "object", "properties": { "message": { "type": "string", "description": "Message providing context on the rule / property that failed validation" }, "key": { "type": "string", "description": "Relevant property or rule in the schema associated with failure message" } }, "description": "Specific error details related to invalid / missing request parameters" }, "errPropsDefault": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/errCode" }, "error": { "$ref": "#/components/schemas/errMsg" } } }, "errPropsValidation": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/errCode" }, "details": { "$ref": "#/components/schemas/errValidation" } } }, "integrationArchiving": { "type": "string", "description": "Set to `ibm` to archive to IBM Cloud Object Storage" }, "bucket": { "type": "string", "description": "Name of the bucket." }, "endpoint": { "type": "string", "description": "Private endpoint associated with the bucket." }, "apikey": { "type": "string", "description": "API key that is needed to authenticate with the Cloud Object Storage service." }, "resourceinstanceid": { "type": "string", "description": "CRN of the Cloud Object Storage instance ID where the bucket is available." }, "accountname": { "type": "string", "description": "Account name" }, "accountkey": { "type": "string", "description": "Account key" }, "projectid": { "type": "string", "description": "Project ID" }, "space": { "type": "string", "description": "Space" }, "accesskey": { "type": "string", "description": "Access key" }, "secretkey": { "type": "string", "description": "Secret key" }, "authurl": { "type": "string", "description": "Auth URL" }, "expires": { "type": "string", "description": "Expires" }, "username": { "type": "string", "description": "Username" }, "tenantname": { "type": "string", "description": "Tenant name" }, "uuid4": { "type": "string", "format": "uuid4", "example": "03290da0-79a9-4090-9189-efb853d049ec" }, "corsHeaders": { "type": "object", "properties": { "access-control-allow-origin": { "type": "string" }, "access-control-allow-methods": { "type": "string" }, "access-control-allow-headers": { "type": "string" }, "access-control-max-age": { "type": "string" } } }, "keyResource": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/keyId" }, "key": { "$ref": "#/components/schemas/keyValue" }, "name": { "$ref": "#/components/schemas/keyName" }, "type": { "$ref": "#/components/schemas/keyType" }, "created": { "$ref": "#/components/schemas/keyCreated" } } }, "keysPut": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/keyName" } }, "additionalProperties": false, "minProperties": 1 }, "memberResource": { "type": "object", "properties": { "email": { "$ref": "#/components/schemas/memberEmail" }, "role": { "$ref": "#/components/schemas/role" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/rbacGroupId" } } } }, "membersPut": { "type": "object", "properties": { "role": { "$ref": "#/components/schemas/role" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/rbacGroupId" } } }, "additionalProperties": false, "minProperties": 1 }, "enterpriseResource": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/accountId" }, "enterprise": { "$ref": "#/components/schemas/enterpriseId" }, "retention": { "$ref": "#/components/schemas/retention" }, "owner": { "$ref": "#/components/schemas/ownerEmail" }, "retentionPeriods": { "$ref": "#/components/schemas/retentionPeriods" }, "plan": { "$ref": "#/components/schemas/plan" }, "servicekey": { "$ref": "#/components/schemas/keyValue" } } }, "enterprisePut": { "type": "object", "properties": { "retention": { "$ref": "#/components/schemas/retention" }, "owner": { "$ref": "#/components/schemas/ownerEmail" } }, "additionalProperties": false, "minProperties": 1 }, "boardRequest": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/accountId" }, "title": { "type": "string" }, "category": { "type": "array", "items": { "type": "string" } } } }, "errResponse": { "type": "object", "properties": { "error": { "type": "string", "description": "A human-readable description of the error" }, "code": { "type": "string", "description": "A unique code for the type of error" }, "status": { "type": "string", "description": "The status of the request" } } }, "screenResource": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true, "description": "The identifier of this screen." }, "account": { "type": "string", "readOnly": true, "description": "The account this screen belongs to." }, "title": { "type": "string", "description": "The title of this screen." }, "ratio": { "type": "string", "enum": [ "3:2", "4:3", "5:4", "16:9", "16:10", "21:9" ], "description": "The width to height aspect ratio of this screen." }, "rotate90Degrees": { "type": "boolean", "description": "Whether the screen is rotated 90 degrees. Setting to true effectively swaps the width to height ratio." }, "background": { "type": "string", "enum": [ "dark", "light" ], "description": "The background color to use when viewing the screen." }, "categories": { "type": "array", "items": { "type": "string" }, "description": "A list of string categories the screen belongs to." }, "widgets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of this widget." }, "type": { "type": "string", "enum": [ "count", "gauge", "table", "time-shifted-graph" ], "description": "The type for this widget." }, "operation": { "type": "string", "enum": [ "count", "min", "max", "avg", "cum", "diff", "percentile-75", "percentile-85", "percentile-95", "percentile-99" ], "description": "The type of operation to perform on the field indicated in the \u201cfield\u201d option. If the \"field\" option is set to all lines, only \"count\" can be used and other values may not display any results." }, "duration": { "type": "string", "oneOf": [ { "enum": [ "hourly-compare", "daily-compare", "weekly-compare", "iso-weekly-compare" ] }, { "enum": [ "hourly", "daily", "weekly", "iso-weekly", "1m", "30m", "1h", "2h", "4h", "8h", "12h", "1d", "2d", "4d", "1w", "2w" ] } ], "description": "How far into the past to graph this widget. Time shifted graph widgets must use time shifted durations e.g. \"iso-weekly-compare\". All other widgets must use regular durations e.g. \"hourly\"." }, "field": { "type": "string", "description": "Which field is being operated on and displayed in this widget. Use the special field \u201c__ALL__LINES__\u201d to perform the operation on all lines." }, "match": { "type": "string", "description": "A special matching operation done on each value of the field. If the field is a string type then this value is used for equivalence matching. For number types, the supported operators are [\"*\", \">N\", \"=N\", \"<=N\"]. If the field is set the special type \"__ALL_LINES__\", this option is disabled." }, "filter": { "type": "string", "description": "An extra query filter to run to match lines. Must be specified as a Mezmo line query e.g. \u201cstatusCode:>=400\u201d." }, "label": { "type": "string", "description": "A label that is displayed on the widget." }, "position": { "type": "object", "properties": { "start": { "type": "array", "items": {}, "description": "The top left corner of the widget as an [x, y] coordinate." }, "end": { "type": "array", "items": {}, "description": "The bottom right corner of the widget as an [x, y] coordinate." } }, "required": [ "start", "end" ], "description": "The positional coordinates of a widget. Screens coordinates start at at the top left at [1, 1] and increase down and to the right of a screen.", "additionalProperties": false }, "sort": { "type": "string", "oneOf": [ { "enum": [ "asc", "desc" ], "x-required": true } ], "description": "The order in which the rows of a table are sorted. This option is specific to the \"table\" widget." }, "rows": { "type": "integer", "oneOf": [ { "enum": [ 3, 5, 10, 15, 20, 25 ], "x-required": true } ], "description": "How many rows to include for the table. This option is specific to the \"table\" widget." }, "leftLabel": { "type": "string", "oneOf": [ {} ], "description": "Label to display on the left side of a table. This option is specific to the \"table\" widget." }, "rightLabel": { "type": "string", "oneOf": [ {} ], "description": "Label to display on the right side of a table. This option is specific to the \"table\" widget." }, "showBarChart": { "type": "boolean", "oneOf": [ { "x-required": true } ], "description": "Whether the rows of a table should also be displayed as a bar chart. This option is specific to the \"table\" widget." }, "groupBy": { "type": "string", "oneOf": [ { "x-required": true } ], "description": "An additional field with which to group results. This option is specific to the \"table\" widget." }, "min": { "type": "number", "format": "float", "oneOf": [ { "x-required": true } ], "description": "The minimum bounds of the gauge. This option is specific to the \"gauge\" widget." }, "max": { "type": "number", "format": "float", "oneOf": [ { "x-required": true } ], "description": "The maximum bounds of the gauge. This option is specific to the \"gauge\" widget." }, "units": { "type": "string", "oneOf": [ {} ], "description": "A label for the units of this widget. This option is specific to the \"count\" and \"gauge\" widgets." }, "format": { "type": "string", "oneOf": [ { "enum": [ "number-integer", "number-tenths", "number-ten-thousandths", "number-unformatted", "currency-prefix", "currency-postfix", "bytes-si", "percent-integer", "percent-thousandths", "time-HH:mm:ss" ], "x-required": true } ], "description": "How to format the results of this widget. This option is specific to the \"count\", \"gauge\", and \"table\" widgets." } }, "required": [ "id", "type", "operation", "duration", "field", "position" ], "additionalProperties": false } } }, "required": [ "id", "title", "ratio", "rotate90Degrees", "background" ], "additionalProperties": false }, "screenListResource": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true, "description": "The identifier of this screen." }, "account": { "type": "string", "readOnly": true, "description": "The account this screen belongs to." }, "title": { "type": "string", "description": "The title of this screen." } } }, "templateOperators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "key": { "type": "string" }, "keys": { "type": "array", "items": { "type": "string" } }, "field": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" }, "ignoreEmptyElements": { "type": "boolean" }, "delimiter": { "type": "string" }, "preservePairs": { "type": "array", "items": { "type": "string" } }, "operators": { "$ref": "#/components/schemas/templateOperators" } }, "example": [ { "type": "string", "key": "string", "keys": [ "string" ], "field": "string", "start": "string", "end": "string", "ignoreEmptyElements": true, "delimiter": "string", "preservePairs": [ "string" ], "operators": [ { "type": "string", "key": "string", "keys": [ "string" ], "field": "string", "start": "string", "end": "string", "ignoreEmptyElements": true, "delimiter": "string", "preservePairs": [ "string" ], "operators": [ {} ] } ] } ] } } }, "securitySchemes": { "AccessToken": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "This key is used for all apis with the exception of ingest. You can obtain it following\n[these instructions](https://docs.mezmo.com/docs/ingestion-key) and placing\nthe key in the header of your call in the format of `Authorization: Token {accesstoken}`\nFor example:\n```\ncurl -H 'Authorization: Token \n```\n" }, "servicekeyAuth": { "type": "apiKey", "in": "header", "name": "servicekey", "description": "(Deprecated) This key is used for v1 and v2 apis with the exception of ingest.\nService keys can be used by placing your service key in the `Authorization`\nheader of your api call. *NOTE* Usage of the service key auth mechanism has been deprecated\nin favor of IAM Access Tokens. Service keys can no longer be created, but can still be\nused for v1 and v2 apis while the transition takes place\n" }, "enterpriseServiceKeyAuth": { "type": "apiKey", "in": "header", "name": "enterprise-servicekey", "description": "When authorizing against our enterprise endpoints, they expect an enterprise service key\ninstead of a regular organization service key. Some endpoints might expect both an\nenterprise service key and a regular organization service key.\n" }, "apikeyAuth": { "type": "apiKey", "in": "header", "name": "apikey", "description": "(Deprecated) This key is used for ingestion. You can obtain it following\n[these instructions](https://docs.mezmo.com/docs/ingestion-key) and placing\nthe key in the header of your call. *NOTE* Usage of the apikey auth mechanism has been deprecated\nin favor of IAM Access Tokens. Service keys can no longer be created, but can still be\nused for v1 and v2 apis while the transition takes place\n" }, "basicAuth": { "type": "http", "scheme": "basic", "description": "(Deprecated) As an alternative to authenticating with a header value, you can also use basic authentication.\nTo use either `apiKey` or `servicekey` as basic authentication, simply pass the key\nas the username with no password. For example:\n```\ncurl https://api.logdna.com/v1/config/view -u INSERT_API_KEY:\n```\n" } } } }